AGENTS.md

1# Graphiti Memory
2 
3This directory contains the Graphiti-backed memory integration for CoPilot.
4This file is developer documentation only — it is NOT injected into LLM prompts.
5Runtime prompt instructions live in `prompting.py:get_graphiti_supplement()`.
6 
7## Scope
8 
9- Keep Graphiti and FalkorDB-specific logic in this package.
10- Prefer changes here over scattering Graphiti behavior across unrelated copilot modules.
11 
12## Debugging
13 
14- Use raw FalkorDB queries to inspect stored nodes, episodes, and `RELATES_TO` facts before changing retrieval behavior.
15- Distinguish user-provided facts, assistant-generated findings, and provenance/meta entities when evaluating memory quality.
16 
17## Design Intent
18 
19- Preserve per-user isolation through `group_id`-scoped databases and clients.
20- Be careful about memory pollution from assistant/tool phrasing; extraction quality matters as much as ingestion success.
21- Keep warm-context and tool-driven recall resilient: failures should degrade gracefully rather than break chat execution.
22 
23## Query Cookbook
24 
25Run everything from `autogpt_platform/backend` and use `poetry run ...`.
26 
27Get the `group_id` for a user:
28 
29```bash
30poetry run python - <<'PY'
31from backend.copilot.graphiti.client import derive_group_id
32print(derive_group_id("883cc9da-fe37-4863-839b-acba022bf3ef"))
33PY
34```
35 
36Inspect graph counts:
37 
38```bash
39poetry run python - <<'PY'
40import asyncio
41from backend.copilot.graphiti.client import derive_group_id
42from backend.copilot.graphiti.config import graphiti_config
43from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
44 
45USER_ID = "883cc9da-fe37-4863-839b-acba022bf3ef"
46GROUP_ID = derive_group_id(USER_ID)
47 
48QUERIES = {
49    "entities": "MATCH (n:Entity) RETURN count(n) AS count",
50    "episodes": "MATCH (n:Episodic) RETURN count(n) AS count",
51    "communities": "MATCH (n:Community) RETURN count(n) AS count",
52    "relates_to_edges": "MATCH ()-[e:RELATES_TO]->() RETURN count(e) AS count",
53}
54
55async def run():
56    driver = AutoGPTFalkorDriver(
57        host=graphiti_config.falkordb_host,
58        port=graphiti_config.falkordb_port,
59        password=graphiti_config.falkordb_password or None,
60        database=GROUP_ID,
61    )
62    try:
63        for name, query in QUERIES.items():
64            records, _, _ = await driver.execute_query(query)
65            print(name, records[0]["count"])
66    finally:
67        await driver.close()
68 
69asyncio.run(run())
70PY
71```
72 
73List entities or relation-name counts:
74 
75```bash
76poetry run python - <<'PY'
77import asyncio
78from backend.copilot.graphiti.client import derive_group_id
79from backend.copilot.graphiti.config import graphiti_config
80from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
81 
82USER_ID = "883cc9da-fe37-4863-839b-acba022bf3ef"
83GROUP_ID = derive_group_id(USER_ID)
84
85async def run():
86    driver = AutoGPTFalkorDriver(
87        host=graphiti_config.falkordb_host,
88        port=graphiti_config.falkordb_port,
89        password=graphiti_config.falkordb_password or None,
90        database=GROUP_ID,
91    )
92    try:
93        records, _, _ = await driver.execute_query(
94            "MATCH (n:Entity) RETURN n.name AS name, n.summary AS summary ORDER BY n.name"
95        )
96        print("## entities")
97        for row in records:
98            print(row)
99 
100        records, _, _ = await driver.execute_query(
101            """
102            MATCH ()-[e:RELATES_TO]->()
103            RETURN e.name AS relation, count(e) AS count
104            ORDER BY count DESC, relation
105            """
106        )
107        print("\\n## relation_counts")
108        for row in records:
109            print(row)
110    finally:
111        await driver.close()
112 
113asyncio.run(run())
114PY
115```
116 
117Inspect facts around one node:
118 
119```bash
120poetry run python - <<'PY'
121import asyncio
122from backend.copilot.graphiti.client import derive_group_id
123from backend.copilot.graphiti.config import graphiti_config
124from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
125 
126USER_ID = "883cc9da-fe37-4863-839b-acba022bf3ef"
127GROUP_ID = derive_group_id(USER_ID)
128TARGET = "sarah"
129
130async def run():
131    driver = AutoGPTFalkorDriver(
132        host=graphiti_config.falkordb_host,
133        port=graphiti_config.falkordb_port,
134        password=graphiti_config.falkordb_password or None,
135        database=GROUP_ID,
136    )
137    try:
138        records, _, _ = await driver.execute_query(
139            """
140            MATCH (a)-[e:RELATES_TO]->(b)
141            WHERE (exists(a.name) AND toLower(a.name) = $target)
142               OR (exists(b.name) AND toLower(b.name) = $target)
143            RETURN a.name AS source, e.name AS relation, e.fact AS fact, b.name AS target
144            ORDER BY e.created_at
145            """,
146            target=TARGET,
147        )
148        for row in records:
149            print(row)
150    finally:
151        await driver.close()
152 
153asyncio.run(run())
154PY
155```
156 
157Inspect all chat messages for a user:
158 
159```bash
160poetry run python - <<'PY'
161import asyncio
162from prisma import Prisma
163 
164USER_ID = "883cc9da-fe37-4863-839b-acba022bf3ef"
165
166async def run():
167    db = Prisma()
168    await db.connect()
169    try:
170        rows = await db.query_raw(
171            '''
172            select cm."sessionId" as session_id,
173                   cm.sequence,
174                   cm.role,
175                   left(cm.content, 260) as content,
176                   cm."createdAt" as created_at
177            from "ChatMessage" cm
178            join "ChatSession" cs on cs.id = cm."sessionId"
179            where cs."userId" = $1
180            order by cm."createdAt", cm.sequence
181            ''',
182            USER_ID,
183        )
184        for row in rows:
185            print(row)
186    finally:
187        await db.disconnect()
188 
189asyncio.run(run())
190PY
191```
192 
193Notes:
194 
195- `RELATES_TO` edges hold semantic facts. Inspect `e.name` and `e.fact`.
196- `MENTIONS` edges are provenance from episodes to extracted nodes.
197- Prefer directed queries `->` when checking for duplicates; undirected matches double-count mirrored edges.
198