project-athena 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.0 — 2026-10-03
+
+Agent memory: coding agents can now record what they learn — decisions and why, gotchas, bug root causes, conventions — and later sessions recall it. Memory lives in `.athena/memory/` as plain Markdown you commit and review like code. Anything an agent writes is `unreviewed` (INFERRED) until you confirm it (`athena memory review`, or the Memory page in `athena open`); entries turn `stale` when the files they describe change. Secrets are refused, and text that looks like it is trying to instruct the agent is flagged and kept out of recall.
+
+After upgrading, run `athena analyze` (or `athena agents add <agent>`) so your agent instructions mention `recall` and `remember`.
+
+### Project memory
+
+- New `athena memory` commands for the project memory in `.athena/memory/`: `list` (`--kind`, `--status`, `--stale`), `show`, `add` (`--kind`, `--title`, `--details` or `--details -` for stdin, repeatable `--file`/`--tag`, `--evidence`, `--supersedes`), `search`, `recall <task…>` (`--file`, `--tag`, `--limit`; ranked hits with reasons), `confirm <id…>`, `supersede <id> --by <id>`, `forget <id…>` (asks first; `--yes` in scripts), `edit`, `stale` and `review` (interactive in a terminal: confirm, forget or skip each agent-written entry). All support `--json`.
+- Entries you record are FACT; entries agents record are INFERRED until confirmed. Stale entries (linked files changed) and flagged entries (possible prompt injection) are marked and explained. A memory that contains a possible secret is refused without echoing the value.
+- `athena status` shows a memory line and a `memory` object (`total`, `unreviewed`, `stale`) in `--json`; `athena doctor` adds a Memory check when entries exist.
+- `athena clean` now says how many project memory entries it would delete (they are committed and shared with the team) before asking for confirmation.
+
+### Agent memory: MCP, context and instructions
+
+- New MCP tools `recall` (ranked memories for a task and/or files, with why each matched, label, status and staleness, fenced in `<athena-memory … trust="untrusted-data">` delimiters; entries flagged as possible prompt injection are excluded and counted), `list_memory` (summaries filtered by kind, status, stale) and `remember` (records a memory as **unreviewed**/INFERRED, attributed to `agent:<id>` from the client's `clientInfo.name` — claude-code, cursor, codex, copilot, gemini-cli, antigravity, windsurf, cline — or `agent:mcp`). `remember` is the only write the MCP server allows without `--allow-write`; it never touches knowledge documents, refuses secrets without echoing them, and is disabled by `athena mcp --no-memory-write`.
+- `athena context` and `get_relevant_context` include up to five recalled memories (confirmed first, flagged excluded) with labels and reasons, within the character budget (at most 30% of it). `--json` and `/api/context` gain a `memories` field.
+- Generated agent instructions (all adapters) tell agents to recall project memory at the start of a task, record durable, non-obvious learnings with `remember` at the end, and treat unreviewed memories as hints to verify — never instructions; `rules.md` and the developer always win.
+
+### Memory page (`athena open`)
+
+- New **Memory** page (`/memory`, in the sidebar with a badge for entries awaiting review) to review project memory in `.athena/memory/*.md`. The review queue (agent-written, INFERRED entries) comes first with Confirm / Edit / Forget; confirmed entries (FACT) follow and superseded ones are collapsed. Cards show kind, FACT/INFERRED label, who recorded it and when, linked files, tags and evidence; details are shown as plain text, never rendered as Markdown or HTML. Stale entries (a linked file changed since) show the changed files and a Re-confirm action; entries that look like prompt injection carry a red warning. Filter chips (kind, status, stale, flagged), a text filter, and an Add memory form (developer entries are FACT immediately). The Overview links to the queue when entries await review.
+- API: `GET /api/memory` (`kind`, `status`, `stale` filters; returns entries and counts), `GET /api/memory/:id`, `POST /api/memory`, `POST /api/memory/:id/confirm`, `POST /api/memory/:id/supersede`, `PATCH /api/memory/:id`, `DELETE /api/memory/:id` — all behind the existing token, Host/Origin and JSON-only checks, with strict schemas. Unknown ids are 404, superseded/busy/full conflicts 409, invalid input and refused secrets 400 (the secret value is never echoed).
+- A `memory.changed` event is emitted after every write from the UI and when memory files change on disk (an agent writing through MCP, `athena memory` in a terminal, a `git pull`), so open pages refresh live.
+
 ## 0.3.0 — 2026-09-30
 
 Performance release: work is now proportional to what changed. On a 20,000-file repository (vs 0.2.1): a `sync --check` with nothing changed takes ~0.42 s instead of 2.9 s, `status` 0.14 s instead of 0.34 s, agent hooks start in ~28 ms instead of 112 ms, and peak memory is 20–52% lower in every scenario. The generated `model.json` is unchanged (golden-tested against the 0.2.1 analyzer). Benchmarks: `npm run bench`.

package/README.md

@@ -58,6 +58,7 @@ Generated content sits between `athena:generated` markers. Anything outside the
 | `athena sync` | Show which documents would change and why (with diffs), then apply after confirmation (`--yes`, `--dry-run`, `--diff`, `--check` for CI) |
 | `athena watch` | Watch the project and propose updates as files change (`--auto-apply` to write automatically) |
 | `athena doctor` | Check the installation, project, knowledge files and agent integrations |
+| `athena memory` | `list`, `show`, `add`, `search`, `recall`, `confirm`, `supersede`, `forget`, `edit`, `stale`, `review` — project memory in `.athena/memory/` (see [Project memory](#project-memory)) |
 | `athena rules` | `list`, `add "<rule>" --section <name>`, `edit`, `enable`, `disable`, `remove` |
 | `athena agents` | `list`, `add <claude-code\|cursor\|codex\|copilot\|gemini-cli\|antigravity\|windsurf\|cline\|agents-md\|all>`, `remove` |
 | `athena activity` | Show AI agent activity observed through hooks (`-n`, `--agent`) |
@@ -66,15 +67,48 @@ Generated content sits between `athena:generated` markers. Anything outside the
 | `athena git-hook` | `install` (`--review`), `uninstall`, `status` — a Git pre-commit hook that blocks commits when knowledge is out of date |
 | `athena context <task>` | Show which knowledge an agent should read for a task (`--full`, `--json`) |
 | `athena graph` | Inspect the project graph (`--build`, `--search`, `--node`, `--kind`) |
-| `athena mcp` | Serve project intelligence to agents over MCP (stdio; `--allow-write`) |
+| `athena mcp` | Serve project intelligence to agents over MCP (stdio; `--allow-write`, `--no-memory-write`) |
 | `athena ai` | `status`, `enrich` — optional AI suggestions (`--consent`, `--dry-run`) |
 | `athena open` | Start (or reuse) the local web UI on `127.0.0.1`, watch for changes, and open it (`--port`, `--no-open`, `--no-watch`) |
-| `athena clean` | Remove `.athena/` and Athena integration blocks |
+| `athena clean` | Remove `.athena/` (including project memory) and Athena integration blocks |
 
 Global flags: `--json`, `--quiet`, `--cwd <dir>`, `--no-color`.
 
  They print *Not available yet* and exit with code 2. See [docs/ROADMAP.md](docs/ROADMAP.md).
 
+## Project memory
+
+Agents rediscover the same things every session: why the queue uses advisory locks, that tests need `TZ=UTC`, which bug the retry guard fixes. Athena keeps these as **project memory** in `.athena/memory/` — one Markdown file per kind (`decisions.md`, `gotchas.md`, `bugs.md`, `conventions.md`, `todos.md`, `facts.md`). Commit it: the team shares it and reviews changes in pull requests. Text you write outside the `athena:memory` markers is kept as written.
+
+- **Evidence labels.** An entry you record is `confirmed` (**FACT**). An entry an agent records is `unreviewed` (**INFERRED**) until you confirm it.
+- **Staleness.** Entries can link files. When a linked file changes, the entry is reported **stale** until you confirm it again (which re-anchors it), edit it or forget it.
+- **Safety.** Entries that look like a secret are refused (the value is never stored or printed). Entries that address the agent instead of describing the project (possible prompt injection) are flagged and never recalled automatically.
+
+```bash
+athena memory add --kind decision --title "Queue uses advisory locks" \
+  --file src/jobs/queue.ts --tag jobs --evidence "PR #412"
+git log -1 --format=%B | athena memory add --kind bug --title "Double refund on webhook retry" --details -
+athena memory list                 # --kind, --status unreviewed|confirmed|superseded, --stale
+athena memory review               # walk agent-written entries: [c]onfirm [e]dit later [f]orget [s]kip [q]uit
+athena memory recall "change the refund flow" --file src/api/refunds.ts
+athena memory stale                # entries whose linked files changed
+athena memory confirm m-1a2b3c m-4d5e6f
+athena memory supersede m-1a2b3c --by m-7a8b9c   # keep as history
+athena memory forget m-1a2b3c      # asks first; --yes in scripts
+```
+
+```text
+$ athena memory list
+ID        KIND       LABEL    STATUS             TITLE · SOURCE
+m-b74d24  gotcha     INFERRED unreviewed         Refund webhook retries twice · agent:claude-code
+m-815cd7  decision   FACT     confirmed  stale   Queue uses advisory locks · developer
+
+2 entries · 1 confirmed · 1 unreviewed · 1 stale · source: .athena/memory/
+1 entry written by agents is INFERRED until reviewed: run `athena memory review`.
+```
+
+Every command supports `--json`. `athena memory review` is interactive only in a terminal; elsewhere it lists the unreviewed entries and exits 0. `athena status` and `athena doctor` show how many entries are unreviewed or stale, and `athena clean` warns before deleting project memory.
+
 ## Keeping knowledge in sync
 
 ```text
@@ -249,11 +283,19 @@ Documents to read
 
 - **Deterministic.** The same task and project state always produce the same selection, with a stated reason for each document. No AI is involved.
 - **Sections, not whole files.** Only the relevant sections are returned, under a character budget, with your rules always included.
+- **Project memory.** Up to five recalled memories from `.athena/memory/` (confirmed ones first, possible prompt injections excluded) are included with their label (`FACT` once a developer confirmed them, `INFERRED` while unreviewed), whether they are stale, and why they matched. They share the character budget (at most 30% of it) and appear in `--full` output and as `memories` in `--json`.
 - **Project graph.** `athena graph --build` writes `.athena/graph.json`: packages, files, routes, entities, frameworks and commands, connected by `contains`, `imports`, `handles`, `defines` and `depends_on`. It comes from the analysis, so it never asserts more than DETECTED evidence.
 
-**MCP.** `athena mcp` serves this to any MCP-capable agent over stdio, and `athena agents add` registers it (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor, `[mcp_servers.athena]` in `.codex/config.toml` for Codex, `servers.athena` in `.vscode/mcp.json` for GitHub Copilot in VS Code, `mcpServers.athena` in `.gemini/settings.json` for Gemini CLI). Tools: `get_relevant_context`, `get_project_context`, `get_architecture`, `get_database_schema`, `get_api_context`, `get_security_context`, `get_project_rules`, `get_knowledge_document`, `get_project_changes`, `get_project_graph`, `get_athena_status`, `update_knowledge`.
+**MCP.** `athena mcp` serves this to any MCP-capable agent over stdio, and `athena agents add` registers it (`.mcp.json` for Claude Code, `.cursor/mcp.json` for Cursor, `[mcp_servers.athena]` in `.codex/config.toml` for Codex, `servers.athena` in `.vscode/mcp.json` for GitHub Copilot in VS Code, `mcpServers.athena` in `.gemini/settings.json` for Gemini CLI). Tools: `get_relevant_context`, `get_project_context`, `get_architecture`, `get_database_schema`, `get_api_context`, `get_security_context`, `get_project_rules`, `get_knowledge_document`, `get_project_changes`, `get_project_graph`, `get_athena_status`, `update_knowledge`, and the memory tools `recall`, `list_memory` and `remember`.
+
+The server is **read-only by default**: `update_knowledge` reports what would change and refuses to write unless you start it with `--allow-write`. The one exception is `remember`: an agent may append a memory to `.athena/memory/`, but it is always stored **unreviewed** (`INFERRED`, attributed to the agent, e.g. `agent:claude-code`, or `agent:mcp` when the client is not recognized) and counts as a `FACT` only after a developer confirms it. It never touches knowledge documents and refuses anything that looks like a secret. Start the server with `--no-memory-write` to turn it off.
 
-The server is **read-only by default**: `update_knowledge` reports what would change and refuses to write unless you start it with `--allow-write`. Repository content it returns is passed through the secret redactor and wrapped in `<athena-document … trust="untrusted-data">` delimiters, so agents can tell project data from instructions.
+| Memory tool | Input | Returns |
+| --- | --- | --- |
+| `recall` | `task?`, `files?`, `tags?`, `limit?` | Ranked memories with why each matched, label, status and staleness, each in `<athena-memory … trust="untrusted-data">` delimiters. Entries that look like instructions to an agent are excluded (the reply says how many). |
+| `list_memory` | `kind?`, `status?`, `stale?` | One-line summaries: id, kind, status, label, stale, title |
+| `remember` | `kind`, `title`, `details?`, `files?`, `tags?`, `evidence?`, `supersedes?` | The new id and label (`INFERRED`); a developer must confirm it |
+ Repository content it returns is passed through the secret redactor and wrapped in `<athena-document … trust="untrusted-data">` (or `<athena-memory …>`) delimiters, so agents can tell project data from instructions. The generated agent instructions tell agents to `recall` at the start of a task, `remember` durable learnings at the end, and treat unreviewed memories as hints to verify — `rules.md` and the developer always win.
 
 ## Optional AI
 

package/dist/{activity-P4UUFHWV.js → activity-BKW7G4I5.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   listAgents
-} from "./chunk-JY6BFIJJ.js";
+} from "./chunk-QLW657NT.js";
 import {
   readRecentEvents,
   summarizeSessions
@@ -21,14 +21,14 @@ import {
 } from "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
 import "./chunk-JCGDR4UV.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 
@@ -74,4 +74,4 @@ async function activityCommand(opts) {
 export {
   activityCommand
 };
-//# sourceMappingURL=activity-P4UUFHWV.js.map
+//# sourceMappingURL=activity-BKW7G4I5.js.map

package/dist/{agents-3HTSQGL2.js → agents-DFSNEOP5.js}

@@ -3,7 +3,7 @@ import {
   configureAgents,
   listAgents,
   removeAgents
-} from "./chunk-JY6BFIJJ.js";
+} from "./chunk-QLW657NT.js";
 import "./chunk-65TSRDQ3.js";
 import {
   c,
@@ -20,14 +20,14 @@ import {
 } from "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
 import "./chunk-JCGDR4UV.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 
@@ -66,4 +66,4 @@ export {
   agentsListCommand,
   agentsRemoveCommand
 };
-//# sourceMappingURL=agents-3HTSQGL2.js.map
+//# sourceMappingURL=agents-DFSNEOP5.js.map

package/dist/{analyze-F3YOILNL.js → analyze-ZY3MXBOI.js}

@@ -4,7 +4,7 @@ import {
   printSummary,
   runWithProgress,
   summarize
-} from "./chunk-DOQMAZL5.js";
+} from "./chunk-XDCKZ5TV.js";
 import {
   printHeader
 } from "./chunk-SHKXELUX.js";
@@ -16,21 +16,22 @@ import {
   requireProjectRoot
 } from "./chunk-XFN7UZCS.js";
 import "./chunk-KBO7XRBW.js";
-import "./chunk-SJOOXO34.js";
-import "./chunk-PANVPNYF.js";
+import "./chunk-GGXPG6OE.js";
+import "./chunk-MPG3IEGB.js";
 import "./chunk-ELKFRTZT.js";
 import "./chunk-2R6PXY6Z.js";
 import "./chunk-PVCIGUIT.js";
 import "./chunk-OLPSEQS5.js";
+import "./chunk-QCC4VJUH.js";
 import "./chunk-JCGDR4UV.js";
-import "./chunk-2RS6TA3D.js";
+import "./chunk-YRIS7ZS6.js";
 import "./chunk-GHFRQAYT.js";
+import "./chunk-INT3IGMQ.js";
 import "./chunk-673EPYYH.js";
 import "./chunk-FQEGEVLY.js";
 import "./chunk-2DY4PUR4.js";
 import "./chunk-IQQBAWSM.js";
 import "./chunk-AD4OZCU2.js";
-import "./chunk-INT3IGMQ.js";
 import "./chunk-XW3MLHI2.js";
 import "./chunk-EUPETUWA.js";
 
@@ -46,4 +47,4 @@ async function analyzeCommand(opts) {
 export {
   analyzeCommand
 };
-//# sourceMappingURL=analyze-F3YOILNL.js.map
+//# sourceMappingURL=analyze-ZY3MXBOI.js.map

package/dist/{chunk-PR53DT7I.js → chunk-3XSDI5WF.js}

@@ -5,13 +5,13 @@ import {
 import {
   whichExecutable
 } from "./chunk-VSYBC3VY.js";
+import {
+  readRecentEvents
+} from "./chunk-65TSRDQ3.js";
 import {
   listRules,
   parseRules
 } from "./chunk-3IS2X2Z7.js";
-import {
-  readRecentEvents
-} from "./chunk-65TSRDQ3.js";
 import {
   findProjectRoot
 } from "./chunk-KBO7XRBW.js";
@@ -24,7 +24,7 @@ import {
 } from "./chunk-OLPSEQS5.js";
 import {
   ADAPTERS
-} from "./chunk-2RS6TA3D.js";
+} from "./chunk-YRIS7ZS6.js";
 import {
   hookCommand
 } from "./chunk-GHFRQAYT.js";
@@ -176,4 +176,4 @@ export {
   findRunningInstance,
   runDoctor
 };
-//# sourceMappingURL=chunk-PR53DT7I.js.map
+//# sourceMappingURL=chunk-3XSDI5WF.js.map

package/dist/{chunk-S7T6VX56.js → chunk-7DZK6WSQ.js}

@@ -5,14 +5,15 @@ import {
   isJson,
   json,
   line,
-  ok
+  ok,
+  sym
 } from "./chunk-Z6QWMJLK.js";
 import {
   requireProjectRoot
 } from "./chunk-XFN7UZCS.js";
 import {
   ADAPTERS
-} from "./chunk-2RS6TA3D.js";
+} from "./chunk-YRIS7ZS6.js";
 import {
   athenaDir
 } from "./chunk-2DY4PUR4.js";
@@ -36,8 +37,11 @@ async function confirm(question) {
 async function cleanCommand(opts) {
   const root = await requireProjectRoot(opts);
   if (!opts.yes) {
-    if (!process.stdin.isTTY) throw new AthenaError("Refusing to delete .athena/ without confirmation.", "Re-run with --yes in non-interactive environments.");
+    const memory = (await (await import("./memory-VSVNLEJC.js")).memorySummary(root))?.total ?? 0;
+    const memoryNote = memory ? `${memory} project memory ${memory === 1 ? "entry" : "entries"} in .athena/memory/ (shared with your team)` : "";
+    if (!process.stdin.isTTY) throw new AthenaError(`Refusing to delete .athena/${memory ? `, including ${memoryNote},` : ""} without confirmation.`, "Re-run with --yes in non-interactive environments.");
     line(`This removes ${c.bold(".athena/")} (including rules.md and your Developer Notes)${opts.keepAgents ? "" : " and Athena blocks/files in agent configurations"}.`);
+    if (memory) line(c.yellow(`${sym.warn} It also deletes ${memoryNote}.`));
     line(dim("If .athena/ is committed to Git you can restore it from history."));
     if (!await confirm("Continue?")) {
       line("Cancelled.");
@@ -58,4 +62,4 @@ export {
   confirm,
   cleanCommand
 };
-//# sourceMappingURL=chunk-S7T6VX56.js.map
+//# sourceMappingURL=chunk-7DZK6WSQ.js.map

package/dist/{chunk-32PRS2MG.js → chunk-DZDI2HRT.js}

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   AnalysisScheduler
-} from "./chunk-XB66PZ6Z.js";
+} from "./chunk-RVTNSNGK.js";
 import {
   applySync,
   needsIndexRefreshOnly
-} from "./chunk-TGJUUB44.js";
+} from "./chunk-KHMBNT66.js";
 import {
   readExclude
-} from "./chunk-PANVPNYF.js";
+} from "./chunk-MPG3IEGB.js";
 import {
   IgnoreMatcher,
   factsConfigHash
@@ -166,4 +166,4 @@ async function watchProject(root, opts) {
 export {
   watchProject
 };
-//# sourceMappingURL=chunk-32PRS2MG.js.map
+//# sourceMappingURL=chunk-DZDI2HRT.js.map

package/dist/{chunk-EF6GHOIN.js → chunk-FVCDMQUQ.js}

@@ -6,7 +6,7 @@ import {
 import {
   loadScan,
   manifestDependencyNames
-} from "./chunk-PANVPNYF.js";
+} from "./chunk-MPG3IEGB.js";
 import {
   API_ROUTE_PATH,
   AUTH_PATH,
@@ -340,4 +340,4 @@ export {
   reviewChanges,
   hasBlockers
 };
-//# sourceMappingURL=chunk-EF6GHOIN.js.map
+//# sourceMappingURL=chunk-FVCDMQUQ.js.map

package/dist/{chunk-SJOOXO34.js → chunk-GGXPG6OE.js}

@@ -3,7 +3,7 @@ import {
   analyzeProject,
   loadScanFromDir,
   persistAnalysisCache
-} from "./chunk-PANVPNYF.js";
+} from "./chunk-MPG3IEGB.js";
 import {
   ATHENA_VERSION
 } from "./chunk-2R6PXY6Z.js";
@@ -16,7 +16,7 @@ import {
 import {
   ADAPTERS,
   applyChanges
-} from "./chunk-2RS6TA3D.js";
+} from "./chunk-YRIS7ZS6.js";
 import {
   mergeDocument,
   renderBlock
@@ -901,4 +901,4 @@ export {
   composeState,
   runPipeline
 };
-//# sourceMappingURL=chunk-SJOOXO34.js.map
+//# sourceMappingURL=chunk-GGXPG6OE.js.map

package/dist/{chunk-TGJUUB44.js → chunk-KHMBNT66.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   projectSession
-} from "./chunk-PDFQ5BFG.js";
+} from "./chunk-WVQC2EGO.js";
 import {
   impactOf
 } from "./chunk-GR4DL2VM.js";
@@ -11,10 +11,10 @@ import {
   indexWithIntegrations,
   planKnowledge,
   writePlannedKnowledge
-} from "./chunk-SJOOXO34.js";
+} from "./chunk-GGXPG6OE.js";
 import {
   analyzeProject
-} from "./chunk-PANVPNYF.js";
+} from "./chunk-MPG3IEGB.js";
 import {
   headMovement
 } from "./chunk-OLPSEQS5.js";
@@ -396,4 +396,4 @@ export {
   HISTORY_SECTIONS,
   staleForCheck
 };
-//# sourceMappingURL=chunk-TGJUUB44.js.map
+//# sourceMappingURL=chunk-KHMBNT66.js.map