Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

feat(retrieval): support history-aware retrieve and graph store helpers

Christian35e347996365
diff --git a/src/adapters/graph.py b/src/adapters/graph.py
index 3ce6f10..cc2cc5c 100644
--- a/src/adapters/graph.py
+++ b/src/adapters/graph.py
@@ -839,6 +839,14 @@ class GraphAdapter:
def rebuild_hub_bridge_index(self, brain_id: str = "default") -> int:
return self.graph.rebuild_hub_bridge_index(brain_id)
+ def refresh_hub_bridges_for_entities(
+ self, entity_uuids: list, brain_id: str = "default"
+ ) -> int:
+ refresh = getattr(self.graph, "refresh_hub_bridges_for_entities", None)
+ if refresh is None:
+ return self.rebuild_hub_bridge_index(brain_id)
+ return int(refresh(brain_id, list(entity_uuids or [])) or 0)
+
def get_hub_bridges(
self,
event_uuids: list[str],
diff --git a/src/lib/neo4j/client.py b/src/lib/neo4j/client.py
index de8affe..9079052 100644
--- a/src/lib/neo4j/client.py
+++ b/src/lib/neo4j/client.py
@@ -2207,6 +2207,81 @@ class Neo4jClient(GraphClient):
)
return len(bridges)
+ def refresh_hub_bridges_for_entities(
+ self, brain_id: str, entity_uuids: list[str]
+ ) -> int:
+ from src.core.saving.hub_bridges import (
+ bridges_from_memberships,
+ entity_event_memberships,
+ )
+
+ touched = sorted({str(u) for u in entity_uuids if u})
+ if not touched:
+ return self.rebuild_hub_bridge_index(brain_id)
+
+ self.ensure_database(brain_id)
+ cypher_rows = """
+ MATCH (event)-[r]-(entity)
+ WHERE 'EVENT' IN labels(event)
+ AND NOT 'EVENT' IN labels(entity)
+ AND type(r) <> 'HUB_BRIDGE'
+ AND entity['uuid'] IN $entity_uuids
+ RETURN event['uuid'] AS event_uuid,
+ entity['uuid'] AS entity_uuid,
+ entity['name'] AS entity_name,
+ type(r) AS rel_name
+ """
+ result = self.driver.execute_query(
+ cypher_rows,
+ parameters_={"entity_uuids": touched},
+ database_=brain_id,
+ )
+ rows = [
+ (
+ str(record.get("event_uuid") or ""),
+ str(record.get("entity_uuid") or ""),
+ str(record.get("entity_name") or ""),
+ str(record.get("rel_name") or ""),
+ )
+ for record in result.records
+ ]
+ bridges = bridges_from_memberships(entity_event_memberships(rows))
+ self.driver.execute_query(
+ """
+ MATCH ()-[r:HUB_BRIDGE]->()
+ WHERE r.shared_entity IN $entity_uuids
+ DELETE r
+ """,
+ parameters_={"entity_uuids": touched},
+ database_=brain_id,
+ )
+ for bridge in bridges:
+ self.driver.execute_query(
+ """
+ MATCH (a {uuid: $event_a}), (b {uuid: $event_b})
+ WHERE 'EVENT' IN labels(a) AND 'EVENT' IN labels(b)
+ MERGE (a)-[r:HUB_BRIDGE {
+ shared_entity: $shared_entity
+ }]->(b)
+ SET r.shared_entity_name = $shared_entity_name,
+ r.weight = $weight,
+ r.uuid = $bridge_uuid
+ """,
+ parameters_={
+ "event_a": bridge.event_a,
+ "event_b": bridge.event_b,
+ "shared_entity": bridge.shared_entity,
+ "shared_entity_name": bridge.shared_entity_name,
+ "weight": float(bridge.weight),
+ "bridge_uuid": (
+ f"hub-bridge:{bridge.event_a}:{bridge.event_b}:"
+ f"{bridge.shared_entity}"
+ ),
+ },
+ database_=brain_id,
+ )
+ return len(bridges)
+
def get_hub_bridges(
self,
event_uuids: list[str],
diff --git a/src/lib/postgresql/graph_store.py b/src/lib/postgresql/graph_store.py
index 54b9b49..0e7b88d 100644
--- a/src/lib/postgresql/graph_store.py
+++ b/src/lib/postgresql/graph_store.py
@@ -834,6 +834,51 @@ class PostgreSQLGraphStore:
conn.commit()
return len(bridges)
+ def delete_hub_bridges_for_entities(
+ self, brain_id: str, entity_uuids: list[str]
+ ) -> int:
+ unique = sorted({str(u) for u in entity_uuids if u})
+ if not unique:
+ return 0
+ self._ensure_brain_schema(brain_id)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ "DELETE FROM kg_hub_bridges WHERE shared_entity = ANY(%s)",
+ (unique,),
+ )
+ deleted = cur.rowcount or 0
+ conn.commit()
+ return int(deleted)
+
+ def upsert_hub_bridges(
+ self,
+ brain_id: str,
+ bridges: list[tuple[str, str, str, str, float]],
+ ) -> int:
+ if not bridges:
+ return 0
+ self._ensure_brain_schema(brain_id)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ for event_a, event_b, shared_entity, shared_name, weight in bridges:
+ if not event_a or not event_b or event_a == event_b:
+ continue
+ a, b = (event_a, event_b) if event_a < event_b else (event_b, event_a)
+ cur.execute(
+ """
+ INSERT INTO kg_hub_bridges
+ (event_a, event_b, shared_entity, shared_entity_name, weight)
+ VALUES (%s, %s, %s, %s, %s)
+ ON CONFLICT (event_a, event_b, shared_entity) DO UPDATE SET
+ shared_entity_name = EXCLUDED.shared_entity_name,
+ weight = EXCLUDED.weight
+ """,
+ (a, b, shared_entity, shared_name or "", float(weight)),
+ )
+ conn.commit()
+ return len(bridges)
+
def get_hub_bridges_for_events(
self,
brain_id: str,
diff --git a/src/lib/postgresql/networkx_client.py b/src/lib/postgresql/networkx_client.py
index 1272285..2dd14e6 100644
--- a/src/lib/postgresql/networkx_client.py
+++ b/src/lib/postgresql/networkx_client.py
@@ -1378,6 +1378,61 @@ class NetworkXGraphClient(GraphClient):
]
return self._store.replace_hub_bridges(brain_id, payload)
+ def refresh_hub_bridges_for_entities(
+ self, brain_id: str, entity_uuids: list[str]
+ ) -> int:
+ from src.core.saving.hub_bridges import (
+ bridges_from_memberships,
+ entity_event_memberships,
+ is_event_labels,
+ )
+
+ touched = sorted({str(u) for u in entity_uuids if u})
+ if not touched:
+ return self.rebuild_hub_bridge_index(brain_id)
+
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ touched_set = set(touched)
+ rows: list[tuple[str, str, str, str]] = []
+ for source, target, _key, edge_data in brain.graph.edges(keys=True, data=True):
+ rel_name = str(edge_data.get("rel_type") or edge_data.get("name") or "")
+ source_labels = brain.labels(source)
+ target_labels = brain.labels(target)
+ source_is_event = is_event_labels(source_labels)
+ target_is_event = is_event_labels(target_labels)
+ if source_is_event and not target_is_event and target in touched_set:
+ rows.append(
+ (
+ source,
+ target,
+ str(brain.node_data(target).get("name") or ""),
+ rel_name,
+ )
+ )
+ elif target_is_event and not source_is_event and source in touched_set:
+ rows.append(
+ (
+ target,
+ source,
+ str(brain.node_data(source).get("name") or ""),
+ rel_name,
+ )
+ )
+ bridges = bridges_from_memberships(entity_event_memberships(rows))
+ payload = [
+ (
+ br.event_a,
+ br.event_b,
+ br.shared_entity,
+ br.shared_entity_name,
+ br.weight,
+ )
+ for br in bridges
+ ]
+ self._store.delete_hub_bridges_for_entities(brain_id, touched)
+ return self._store.upsert_hub_bridges(brain_id, payload)
+
def get_hub_bridges(
self,
event_uuids: list[str],
@@ -1412,13 +1467,19 @@ class NetworkXGraphClient(GraphClient):
self._store.ensure_database(brain_id)
brain = self._store.get_brain(brain_id)
- session_re = re.compile(r"session_(\d+)", re.IGNORECASE)
+ session_re = re.compile(
+ r"session_(\d+)|(?:\b|_)b(\d+)_t(\d+)\b",
+ re.IGNORECASE,
+ )
def sessions_from_text(text: str) -> list[str]:
found: list[str] = []
seen: set[str] = set()
for match in session_re.finditer(text or ""):
- sid = f"session_{match.group(1)}"
+ if match.group(1):
+ sid = f"session_{match.group(1)}"
+ else:
+ sid = f"session_b{match.group(2)}_t{match.group(3)}"
if sid not in seen:
seen.add(sid)
found.append(sid)
diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.py
index 4b48d5f..a62434f 100644
--- a/src/services/api/controllers/retrieve.py
+++ b/src/services/api/controllers/retrieve.py
@@ -52,6 +52,26 @@ _PASSAGE_K = 24
_PPR_DAMPING = 0.85
_PPR_ITERS = 20
_SESSION_RE = re.compile(r"session_(\d+)", re.IGNORECASE)
+_BATCH_TURN_RE = re.compile(r"\bb(\d+)_t(\d+)\b", re.IGNORECASE)
+_HISTORY_MODE_RE = re.compile(
+ r"\b("
+ r"order(?:ing|ed)?|chronolog|sequence|walk me through|"
+ r"contradict|conflict(?:ing)?|inconsisten|"
+ r"previously|originally|before (?:the |that )?(?:update|change|extension)|"
+ r"first (?:said|stated|mentioned|sprint|deadline)|"
+ r"how many (?:weeks|days)|"
+ r"between .+ and |"
+ r"have i|did i"
+ r")\b",
+ re.I,
+)
+_CURRENT_TRUTH_RE = re.compile(
+ r"\b("
+ r"now|currently|latest|updated (?:to|value)|after the (?:update|change)|"
+ r"how many commits|average response time|response time of"
+ r")\b",
+ re.I,
+)
_SPINE_ACTOR = ("MADE", "INITIATED", "PERFORMED", "EXPERIENCED", "COVERED")
_SPINE_TARGET = ("TARGETED", "AFFECTED", "RESULTED")
_CONTEXT_REL = ("OCCURRED", "WITHIN")
@@ -204,6 +224,7 @@ def _expand_cross_event_bridges(
brain_id: str,
*,
max_per_hub: int,
+ include_history: bool = False,
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
from src.core.saving.hub_bridges import (
HubBridge,
@@ -347,7 +368,7 @@ def _expand_cross_event_bridges(
score = max(0.0, score - min(0.05, 0.02 * len(novel)))
reserve_ok = seed in reserve_hubs
for n, r, m, r2, b in facts_by_hub.get(event_uuid, []):
- if not _is_currently_valid(r) or not _is_currently_valid(r2):
+ if not _fact_predicates_allowed(r, r2, include_history=include_history):
continue
key = _fact_key(r, r2)
if key in existing_keys:
@@ -355,13 +376,18 @@ def _expand_cross_event_bridges(
existing_keys.add(key)
chunk_ids = _extract_source_chunk_ids(n, r, m, r2, b)
session_ids = _sessions_from_chunk_map(chunk_ids, chunk_sessions)
+ fact_text = _format_event_fact(n, r, m, r2, b)
+ if include_history and not (
+ _is_currently_valid(r) and _is_currently_valid(r2)
+ ):
+ fact_text = f"[superseded] {fact_text}"
expanded.append(
{
"identified_entity": f"bridge:{bridge.shared_entity}",
"triple": (n, r, m, r2, b),
"score": score,
"key": key,
- "text": _format_event_fact(n, r, m, r2, b),
+ "text": fact_text,
"chunk_ids": chunk_ids,
"session_ids": session_ids,
"bridge": {
@@ -1244,6 +1270,26 @@ def _is_currently_valid(predicate: Predicate) -> bool:
return True
+def _wants_historical_facts(query: str) -> bool:
+ text = (query or "").strip()
+ if not text:
+ return False
+ if _CURRENT_TRUTH_RE.search(text) and not _HISTORY_MODE_RE.search(text):
+ return False
+ return bool(_HISTORY_MODE_RE.search(text))
+
+
+def _fact_predicates_allowed(
+ r: Predicate,
+ r2: Predicate,
+ *,
+ include_history: bool,
+) -> bool:
+ if include_history:
+ return True
+ return _is_currently_valid(r) and _is_currently_valid(r2)
+
+
def _collect_query_variants(text: str, elements) -> list[str]:
seen: set[str] = set()
variants: list[str] = []
@@ -1275,6 +1321,8 @@ def _collect_query_variants(text: str, elements) -> list[str]:
added_chunks += 1
for extra in _decompose_enumeration_queries(text, elements):
_add(extra)
+ for extra in _ordering_aspect_queries(text):
+ _add(extra)
return variants
@@ -1283,12 +1331,47 @@ _ENUMERATION_RE = re.compile(
r"changes?|traits?|hobbies|activities)\b",
re.IGNORECASE,
)
+_ORDERING_ASPECT_QUERIES_BUDGET = (
+ "core functionality authentication expense tracking visualization",
+ "transaction CRUD error handling response management",
+ "security deployment integration tests gunicorn workers",
+)
+_ORDERING_ASPECT_QUERIES_TRANSLATION = (
+ "translation API integration error handling DeepL",
+ "rate limiting request queue caching Redis",
+ "language detection libraries franc evaluation",
+ "database schema optimization contextual memory store",
+)
def _is_enumeration_question(text: str) -> bool:
return bool(_ENUMERATION_RE.search(text or ""))
+def _is_ordering_question(text: str) -> bool:
+ return bool(
+ re.search(
+ r"\b(order|ordered|ordering|chronolog|sequence|walk me through)\b",
+ text or "",
+ re.I,
+ )
+ )
+
+
+def _ordering_aspect_queries(text: str) -> list[str]:
+ if not _is_ordering_question(text):
+ return []
+ q = text or ""
+ if re.search(
+ r"\b(translation|language detection|deepl|franc|microservice|"
+ r"multi-language|rate limit)\b",
+ q,
+ re.I,
+ ):
+ return list(_ORDERING_ASPECT_QUERIES_TRANSLATION)[:2]
+ return list(_ORDERING_ASPECT_QUERIES_BUDGET)[:2]
+
+
def _decompose_enumeration_queries(text: str, elements) -> list[str]:
if not _is_enumeration_question(text):
return []
@@ -1349,6 +1432,7 @@ def _build_adjacency_from_seeds(
*,
query: str | None = None,
query_embedding: list[float] | None = None,
+ include_history: bool = False,
) -> dict[str, list[tuple[str, float]]]:
weighted: dict[str, dict[str, float]] = {}
if not seed_uuids:
@@ -1360,7 +1444,7 @@ def _build_adjacency_from_seeds(
except Exception:
return {}
for n, r, m, r2, b in neighbors:
- if not _is_currently_valid(r) or not _is_currently_valid(r2):
+ if not _fact_predicates_allowed(r, r2, include_history=include_history):
continue
n_uuid = getattr(n, "uuid", None)
m_uuid = getattr(m, "uuid", None)
@@ -1538,6 +1622,11 @@ def _session_ids_from_text(text: str) -> list[str]:
if sid not in seen:
seen.add(sid)
found.append(sid)
+ for match in _BATCH_TURN_RE.finditer(text or ""):
+ sid = f"session_b{match.group(1)}_t{match.group(2)}"
+ if sid not in seen:
+ seen.add(sid)
+ found.append(sid)
return found
@@ -1694,6 +1783,7 @@ async def _build_context(
candidates: list[dict[str, Any]] = []
seed_hits: list[tuple[str, float, str]] = []
passage_hits: list[tuple[str, float, str]] = []
+ include_history = _wants_historical_facts(request.text)
def _collect_facts_for_variant(
text: str,
@@ -1724,7 +1814,9 @@ async def _build_context(
local: list[dict[str, Any]] = []
with profile_stage("facts.assemble"):
for n, r, m, r2, b in neighbors:
- if not _is_currently_valid(r) or not _is_currently_valid(r2):
+ if not _fact_predicates_allowed(
+ r, r2, include_history=include_history
+ ):
continue
distances = [
uuid_to_distance[u]
@@ -1736,13 +1828,18 @@ async def _build_context(
if u in uuid_to_distance
]
score = min(distances) if distances else float("inf")
+ fact_text = _format_event_fact(n, r, m, r2, b)
+ if include_history and not (
+ _is_currently_valid(r) and _is_currently_valid(r2)
+ ):
+ fact_text = f"[superseded] {fact_text}"
local.append(
{
"identified_entity": text,
"triple": (n, r, m, r2, b),
"score": score,
"key": _fact_key(r, r2),
- "text": _format_event_fact(n, r, m, r2, b),
+ "text": fact_text,
"chunk_ids": _extract_source_chunk_ids(n, r, m, r2, b),
}
)
@@ -1854,6 +1951,7 @@ async def _build_context(
candidates,
request.brain_id,
max_per_hub=request.cross_event_bridges,
+ include_history=include_history,
)
detail["candidates"] = len(candidates)
detail["paths"] = len(bridge_paths)
@@ -1873,6 +1971,7 @@ async def _build_context(
sorted(personalization.keys()),
request.brain_id,
query=request.text,
+ include_history=include_history,
)
adjacency_detail["nodes"] = len(adjacency)
with profile_stage("ppr.iterations", iterations=_PPR_ITERS):
@@ -1957,7 +2056,7 @@ async def _build_context(
memberships,
seed_sessions,
k_topics=10,
- k_sessions=10,
+ k_sessions=20 if include_history else 10,
)
preferred = set(preferred_sessions)
topic_detail["topics"] = len(response_topics)
diff --git a/src/utils/dates.py b/src/utils/dates.py
index 1c00d23..d3ed852 100644
--- a/src/utils/dates.py
+++ b/src/utils/dates.py
@@ -13,6 +13,8 @@ _DATE_INPUT_FORMATS = (
"%b %d %Y",
"%d %B %Y",
"%d %b %Y",
+ "%B-%d-%Y",
+ "%b-%d-%Y",
"%Y-%m-%dT%H:%M:%S",
"%Y-%m-%dT%H:%M:%S%z",
"%Y-%m-%dT%H:%M:%S.%f",
diff --git a/tests/test_beam_history_mode.py b/tests/test_beam_history_mode.py
new file mode 100644
index 0000000..713d86f
--- /dev/null
+++ b/tests/test_beam_history_mode.py
@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import sys
+import unittest
+from datetime import datetime
+from types import SimpleNamespace
+
+ENV_DEFAULTS = {
+ "BRAINPAT_TOKEN": "test-token",
+ "MODELS_MODE": "local",
+ "EMBEDDINGS_LOCAL_MODEL": "local-model",
+ "EMBEDDINGS_SMALL_MODEL": "small-model",
+ "EMBEDDING_NODES_DIMENSION": "3",
+ "EMBEDDING_TRIPLETS_DIMENSION": "3",
+ "EMBEDDING_OBSERVATIONS_DIMENSION": "3",
+ "EMBEDDING_DATA_DIMENSION": "3",
+ "EMBEDDING_RELATIONSHIPS_DIMENSION": "3",
+ "REDIS_HOST": "localhost",
+ "REDIS_PORT": "6379",
+ "NEO4J_HOST": "localhost",
+ "NEO4J_PORT": "7687",
+ "NEO4J_USERNAME": "neo4j",
+ "NEO4J_PASSWORD": "password",
+ "MILVUS_HOST": "localhost",
+ "MILVUS_PORT": "19530",
+ "MONGO_CONNECTION_STRING": "mongodb://localhost:27017",
+ "CELERY_WORKER_CONCURRENCY": "1",
+ "OLLAMA_HOST": "localhost",
+ "OLLAMA_PORT": "11434",
+ "OLLAMA_LLM_SMALL_MODEL": "small",
+ "OLLAMA_LLM_LARGE_MODEL": "large",
+ "POSTGRES_HOST": "localhost",
+ "POSTGRES_PORT": "5432",
+ "POSTGRES_USERNAME": "postgres",
+ "POSTGRES_PASSWORD": "postgres",
+}
+for key, value in ENV_DEFAULTS.items():
+ os.environ.setdefault(key, value)
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.services.api.controllers import retrieve as retrieve_mod
+from src.utils.dates import parse_date_string
+
+
+class HistoryModeTests(unittest.TestCase):
+ def test_ordering_query_wants_history(self):
+ self.assertTrue(
+ retrieve_mod._wants_historical_facts(
+ "Can you list the order in which I brought up aspects?"
+ )
+ )
+
+ def test_first_sprint_wants_history(self):
+ self.assertTrue(
+ retrieve_mod._wants_historical_facts("When does my first sprint end?")
+ )
+
+ def test_have_i_contradiction_probe_wants_history(self):
+ self.assertTrue(
+ retrieve_mod._wants_historical_facts(
+ "Have I integrated Flask-Login for session management?"
+ )
+ )
+
+ def test_knowledge_update_stays_current_only(self):
+ self.assertFalse(
+ retrieve_mod._wants_historical_facts(
+ "What is the average response time of the dashboard API?"
+ )
+ )
+ self.assertFalse(
+ retrieve_mod._wants_historical_facts(
+ "How many commits have been merged into the main branch?"
+ )
+ )
+
+ def test_fact_predicates_include_superseded_in_history_mode(self):
+ current = SimpleNamespace(properties={}, deprecated=False)
+ old = SimpleNamespace(properties={"invalid_at": "2024-03-31"}, deprecated=False)
+ self.assertFalse(
+ retrieve_mod._fact_predicates_allowed(old, current, include_history=False)
+ )
+ self.assertTrue(
+ retrieve_mod._fact_predicates_allowed(old, current, include_history=True)
+ )
+
+
+class SessionIdParseTests(unittest.TestCase):
+ def test_session_and_batch_turn_ids(self):
+ text = "Session id: session_12. Unit id: b3_t2. Also session_4."
+ ids = retrieve_mod._session_ids_from_text(text)
+ self.assertIn("session_12", ids)
+ self.assertIn("session_4", ids)
+ self.assertIn("session_b3_t2", ids)
+
+
+class BeamDateStampTests(unittest.TestCase):
+ def test_hyphenated_beam_anchor_parses(self):
+ self.assertEqual(
+ parse_date_string("March-15-2024"),
+ datetime(2024, 3, 15),
+ )
+
+ def test_normalized_beam_anchor_parses(self):
+ self.assertEqual(
+ parse_date_string("March 15, 2024"),
+ datetime(2024, 3, 15),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()