Skip to content
Merged
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
4 changes: 2 additions & 2 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,8 @@
# AGENTMEMORY_GRAPH_WEIGHT=0.2 # Graph traversal bonus on smart-search ranking
# TOKEN_BUDGET=2000 # Max tokens injected via mem::context per session
# 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.
# SUMMARIZE_CHUNK_TOKENS=50000 # Prompt-token budget per chunk when mem::summarize map-reduces a large session (chunk-summarize → reduce-merge). Observations are measured with the provider's tokenize route when it has one (llama.cpp-style POST /tokenize) and estimated at chars/3 otherwise; the ~400-token system prompt is reserved inside this budget. A 50k chunk summarizes cold in 60–89s on a local 35B model.
# SUMMARIZE_CHUNK_CONCURRENCY=2 # Parallel chunk LLM calls during chunked summarize. A local broker serialises chunks on one GPU, so more concurrency only stretches each call: AGENTMEMORY_LLM_TIMEOUT_MS is sized for 2. Raise it for hosted providers that run chunks in parallel, and re-measure the timeout if you do.

# --- Retrieval ranking -------------------------------------------------
# Every flag below defaults to the historical behaviour. Turn them on one
Expand Down
47 changes: 47 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,30 @@
# agentmemory — Agent Instructions

## Goal

Put the right Memory in front of an Agent at the moment it needs it, and pay as little as
possible to be able to do that. Every feature here is judged against that sentence.

- **Right content** — Recall returns what bears on the work in hand, not everything that
matched the query. A near-miss that costs the Agent a read is worse than one fewer result.
- **Right moment** — context arrives at hook boundaries (session start, pre-tool-use,
pre-compact) without the Agent having to know to ask. Memory the Agent must remember to
query is memory that goes unused.
- **Right scope** — results are bounded by project, branch, and Session
(`scope: "project" | "global"`, `src/types.ts:277`). One repo's work never surfaces in
another's.
- **Least record that restates** — store the smallest durable claim that reconstructs a
decision later: the conclusion and why, not the transcript that produced it. Observations
are raw and cheap; a Memory earns its place by being worth re-reading.
- **Durable beats recent** — a correction that changes future behaviour outranks a log of
what happened. Volume is a cost, not a measure of success; Eviction is expected, not a
failure mode.
- **Never on the critical path** — memory accelerates a Session and is never a dependency of
one. A dead daemon, a missed hook, or a slow Recall degrades the work; it does not block
it.
- **The Operator's attention is the scarce resource** — disk growth, restarts, and noisy
recall are the real costs, and they land on one person.

## Architecture

agentmemory is a persistent memory system for AI coding agents. It runs as a single process on one in-process Engine ([ADR 0001](./docs/adrs/0001-single-in-process-sqlite-engine.md)) — importing `src/index.ts` *is* starting the daemon. There is no separate runtime to install, spawn, adopt or stop.
Expand Down Expand Up @@ -125,6 +150,11 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no Engine import).
- REST endpoints must whitelist fields — never pass raw request body to `sdk.trigger()`
- Use `recordAudit()` for state-changing operations
- Timestamps: capture once with `new Date().toISOString()` and reuse
- Outbound LLM/embedding calls go through `fetchWithTimeout`, which honors the configured
bound (`OPENAI_TIMEOUT_MS` → `AGENTMEMORY_LLM_TIMEOUT_MS` → 60s) exactly. The in-process
Engine has no invocation timeout, so never reintroduce a ceiling that clamps that bound —
the old 170s `HARD_BUDGET_CAP_MS` cited iii's 180s limit, silently cut every longer
timeout, and still reported the configured value in the error.

## Testing

Expand Down Expand Up @@ -166,6 +196,23 @@ the `@agentmemory/mcp` shim wherever it is invoked as a proxy — `plugin/.mcp.j
running server, not from the shim. The translated `READMEs/` were deleted rather than kept
stale — do not re-add translations without a way to keep them current.

`docs/upstream-issue-triage.yaml` scores every open upstream issue by severity and fix
difficulty. It is a survey of defects in the shared code lineage, used to pick what is worth
fixing *here* — it is not a backlog to merge from, and it is a dated snapshot, not a live
mirror. Re-generate it from `gh issue list` rather than editing rows by hand. Its rows
cross-link the open upstream PRs that claim to fix them; `docs/upstream-pr-triage.yaml`
covers the remaining PRs — the ones that reference no open issue — scored by whether they
land in code this fork carries. Both are read for the defect and the diagnosis, never for
the patch.

Every row in both files carries a `disposition`: `already-fixed` (verified against this tree;
`fixed_by`/`status` names the evidence), `wont-fix` (out of scope here — no iii engine, no npm
publish, no Windows CI, no deploy tree, or a host with no adapter in `src/cli/connect/`;
`wont_fix_reason` says which), or `candidate` — the working set. A row that was opened against
this tree also carries `status`, whose leading token says what the read found
(`fixed-here`, `present-here`, `partly-present-here`, `unresolved`). No `status` means
unchecked: the note is still upstream's claim, not a verified defect.

## Current Stats (v0.9.29)

- 55 MCP tools (all visible by default, `AGENTMEMORY_TOOLS=core` for the 8 essentials)
Expand Down
6 changes: 6 additions & 0 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ A durable distilled record derived from Observations, intended to be recalled la
are content-addressed, so the same content captured twice is one Memory.
_Avoid_: note, fact, item

**Session Summary**:
The distilled account of one Session, produced from its Observations at the Session's end.
A Session Summary is current until an Observation arrives after it was written, and a
current one is reused rather than reproduced.
_Avoid_: session digest, recap

**Entity**:
A named thing the Agent worked with — a file, a symbol, a service, a concept — held as a node
in the graph.
Expand Down
5 changes: 5 additions & 0 deletions docs/adrs/0001-single-in-process-sqlite-engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,3 +66,8 @@ this fork does not execute. Rejected on cost against zero realised benefit.
registration and `trigger()` become direct in-process calls.
- Documentation describing agentmemory as built on iii-engine's three primitives becomes
false for this fork and must be rewritten, not annotated.
- Code that budgeted time against iii's 180s invocation timeout is now bounding itself
against a limit that no longer exists. `fetchWithTimeout`'s 170s `HARD_BUDGET_CAP_MS` was
one such residual: it clamped every configured LLM timeout above it while the error still
reported the unclamped value, so a slow local model looked like a provider failure. Treat
any remaining iii-derived ceiling as a defect, not a safety margin.
Loading
Loading