Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,14 @@
# VECTOR_WEIGHT=0.6 # Hybrid search weight for vector leg
# AGENTMEMORY_GRAPH_WEIGHT=0.2 # Graph traversal bonus on smart-search ranking
# TOKEN_BUDGET=2000 # Max tokens injected via mem::context per session
# Recall context now uses ~/.agentmemory/config.toml for structured budgets.
# Environment overrides still win over config.toml:
# AGENTMEMORY_RECALL_MAX_CONTEXT_TOKENS=800
# AGENTMEMORY_RECALL_RESERVED_BOOTSTRAP_TOKENS=200
# AGENTMEMORY_RECALL_MAX_SEMANTIC_TOKENS=600
# AGENTMEMORY_RECALL_UNKNOWN_AUTO_INJECTION=false
# AGENTMEMORY_RECALL_UNKNOWN_EXPLICIT_SEARCH=true
# AGENTMEMORY_RECALL_TRACE_MAX_DROPPED_ITEMS_PER_REASON=20
# MAX_OBS_PER_SESSION=500 # Per-session observation cap before consolidation kicks in
# SUMMARIZE_CHUNK_SIZE=400 # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.
# SUMMARIZE_CHUNK_CONCURRENCY=6 # Parallel chunk LLM calls during chunked summarize. Default 6 fits ~100-chunk sessions under iii's 180s function-invocation timeout at typical ~8s/call. High-throughput providers (Novita, DeepInfra, DeepSeek) commonly allow 100+ concurrent — bump this for very large imported sessions.
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ agentmemory-debug/

# Lock files — never commit (see feedback_no_lockfiles memory)
package-lock.json
eval/recall/fixtures/local.json
pnpm-lock.yaml
yarn.lock
integrations/hermes/__pycache__/
Expand Down
36 changes: 30 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,30 @@ case "memory_your_tool": {
}
```

### Recall Pattern

Recall is centralized through `RecallCore` (`src/recall/core.ts`). All search paths (`context`, `enrich`, `prompt-submit`, `pre-compact`, MCP `memory_recall`, `memory_smart_search`) route through it instead of calling `hybridSearch` or `kv.list` directly. This ensures every recall produces a traceable `RecallTrace` with selected/dropped items and reasons.

```typescript
const recallCore = new RecallCore(kv, config.recall, hybridSearch.searchWithTrace);
// context generation
registerContextFunction(sdk, kv, config.tokenBudget, recallCore);
// enrichment (PreToolUse)
registerEnrichFunction(sdk, kv, recallCore);
// MCP tools: memory_recall + memory_smart_search with outputMode=structured/context
// route through mem::context which delegates to recallCore
```

**When adding new search/recal paths, you MUST:**
1. Route through `RecallCore` — never bypass it with direct `hybridSearch` or `kv.list`
2. Wire recall trace persistence via `persistRecallTrace()` in `src/recall/trace-store.ts`
3. Register new debug endpoints in `src/triggers/api.ts` (`api::recall-debug` / `api::recall-debug-by-id`)
4. Add corresponding skill docs if the recall path is user-facing

**When adding new KV scopes for recall traces:**
1. `src/state/schema.ts` — add to the KV object (e.g. `recallTraces: { kv: "memory" }`)
2. `src/types.ts` — add the corresponding interface (`RecallTrace`, `RecallItemTrace`, etc.)

### Hook Scripts
Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import). They read JSON from stdin, make HTTP calls to the REST API, and exit. There are two patterns depending on whether Claude Code consumes the script's stdout:

Expand All @@ -114,11 +138,11 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
- Test files go in `test/` with `.test.ts` extension
- Follow existing patterns in `test/crystallize.test.ts` for function tests

## Current Stats (v0.9.16)
## Current Stats (v0.9.27)

- 53 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
- 128 REST endpoints
- 53 MCP tools (core: memory_recall, memory_save, memory_compress_file, memory_file_history, memory_patterns, memory_sessions, memory_smart_search, memory_timeline, memory_profile, memory_export, memory_relations; `AGENTMEMORY_TOOLS=all` for 53)
- 136 REST endpoints
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 15 skills
- 50+ iii functions
- 950+ tests
- 12 hooks, 17 skills (10 invocable + 7 reference)
- 296 registered functions (148 mem::, 137 api::, 6 mcp::, 5 event::)
- 184 source files · ~42,400 LOC · 1,500+ tests · 58 KV scopes
Loading