Memory & Vault
Agent context windows are temporary. Agenties keeps project memory on disk so work can continue across restarts, new sessions, and long-running projects — regardless of which interface or AI assistant you used to give the original instruction. Obsidian and NotebookLM are optional knowledge layers; the operational source of truth stays in the project under .agenties/.
Memory layers
| Layer | Path or provider | Purpose |
|---|---|---|
| Operational truth | .agenties/ | Issues, goals, agents, sessions, shared state, reports, and audit trail. |
| Recent continuity | .agenties/continuity/journal.md | Chronological log of recent meaningful work. |
| Context map | .agenties/continuity/index.md | Compact map of important decisions, fixes, and where to read more. |
| Knowledge vault | Obsidian | Human-readable doctrine, research, decisions, and summaries. |
| Semantic facts | .agenties/memory/facts.json | Auto-extracted durable facts from closed issues and agent events. |
| Semantic recall | NotebookLM | Optional fuzzy lookup over summaries and research material. |
Local project files
Agenties writes durable operational context into the project. These files are designed for machines to update and for humans to inspect when needed.
| File | Use |
|---|---|
.agenties/shared/state.json | Current objective, active agents, open work items, and recent decisions. |
.agenties/issues.json | Backlog and status of project work. |
.agenties/goals.json | Multi-issue execution plans and goal status. |
.agenties/reports/*.md | Design, QA, audit, and continuity reports. |
.agenties/team/*/memory.md | Per-team-member memory. |
Obsidian vault
Obsidian is the human-readable knowledge layer. Use it for doctrine, decisions, session summaries, research, and project notes. Do not use it as a replacement for `.agenties/` operational state. See Obsidian for the full integration guide.
Vault MCP tools
| Tool | Description |
|---|---|
read_vault_note | Read one note by relative path. |
write_vault_note | Write or overwrite a note. |
append_vault_note | Append to a note. |
list_vault_notes | List notes under the project vault folder. |
search_vault_notes | Search notes with bounded excerpts and result caps. |
build_init_context | Build startup context from shared state, continuity files, and vault excerpts. |
NotebookLM
NotebookLM is optional. Treat it as semantic recall or research support. It should receive summaries and curated material, not raw operational dumps. See NotebookLM for the full integration guide.
Session commands
| Command | Description |
|---|---|
/init | Load minimal project context into the orchestrator. |
/wrapup | Write a session summary and prepare the next session. |
/vault | Open or inspect vault notes. |
/memory | Show shared state and recent memory. |
Memory drawer
The Agenties desktop app includes a Memory drawer in the chat interface. It surfaces the most relevant local memory files — shared state, continuity journal, and vault excerpts — so you can inspect what context agents are working from without leaving the chat. Open it from the toolbar during any session.
Semantic Memory
Agenties automatically extracts durable facts from completed issues and agent task-done events and writes them to .agenties/memory/facts.json. These facts persist across restarts, letting future sessions recall what was decided, what integrations are active, and what risks were flagged — without relying on live Claude context.
Facts are categorised automatically based on content keywords. You can also append facts manually via the append_fact MCP tool.
Fact categories
| Category | When used |
|---|---|
decision | Architecture choices, migration decisions, or key direction changes. |
issue_result | Default for closed issues — what was built or fixed. |
project_fact | Stable facts about the project (integrations, versions, configurations). |
user_preference | Conventions and preferences that should persist ("always", "never"). |
integration_state | Active third-party integrations and their status. |
risk | Known risks, vulnerabilities, or technical debt. |
next_step | Deferred work or follow-ups captured across sessions. |
MCP tools
| Tool | Description |
|---|---|
query_facts | Search facts by keyword, category, or scope. Returns most recent first. |
append_fact | Write a new fact. Duplicate detection prevents duplicate entries. |
query_facts for historical decisions over re-reading shared state.Automatic triggers
The sidecar hooks into two events to extract facts without manual intervention:
| Trigger | What is extracted |
|---|---|
| Issue closed (status → done) | Issue title + first 200 chars of description, tagged with issueId. |
| Agent emits task-done with summary | First 300 chars of the summary, tagged with agentId and issueId. |
Scopes
Each fact has a scope field. Most auto-generated facts use project scope. Valid values: project, session, agent, user, global.
Knowledge Graph
Graphify builds a semantic index of your codebase stored at.agenties/graphify/<slug>/graph.json. Agents use it as a fast pre-search before broad file scans. The graph is separate from vault memory and does not replace it — vault notes are human-authored knowledge, the graph is an auto-built file index.
| Tool | Description |
|---|---|
graph_status | Check if the graph is installed and how fresh it is. |
graph_query | Ask a natural-language question and get ranked file pointers. |
graph_update | Rebuild the graph index after major codebase changes. |