project-athena 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # 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`.
+
+After upgrading, the first run rebuilds `.athena/state.json` in the new format automatically. If you use the pre-commit hook, run `athena git-hook install` again so it checks staged content.
+
+### Performance
+
+- `athena open` reuses parsed `.athena` artifacts: a new `ProjectSession` loads `model.json`, `graph.json`, `security-scan.json` and `state.json` once and re-reads them only when the file changes (inode, size or mtime). The overview, graph, context, security and `athena security` paths share it, and the graph summary checks for `model.json` with a stat instead of parsing and validating the whole model.
+- The event stream (`/api/events`) coalesces bursts into one write per 250 ms (intermediate activity states collapse to the latest), serializes each event once for all clients, and applies backpressure: a client that stops reading gets nothing more until its socket drains, keeps at most 100 queued events (oldest dropped) plus the latest activity, and then receives a `resync` frame with the number of events it missed. At most 16 event streams are open at once (503 beyond that).
+- `GET /api/sync` no longer includes each proposed document's full diff; the Sync page fetches a diff from the new `GET /api/sync/:doc` only when the document is expanded.
+- `athena event` (run by agent hooks on every tool call) starts about 2.5× faster and uses about 40% less memory (p50 112 ms / 100 MB → ~45 ms / 57 MB on the 20k-file benchmark): it no longer loads commander or any other command's dependencies. All other commands load their code on demand, which also lowers memory for `status`, `review` and `sync`.
+- `athena event` no longer loads zod: the paths it needs moved to a dependency-free module (`src/core/paths.ts`). p50 of 10 on an Apple M-series laptop: ~43 ms / 57 MB → ~26 ms / 49 MB. The startup test now fails if zod reaches the event chunk.
+- The CLI is now built with code splitting: `dist/cli.js` is a small entry that loads chunks from `dist/` as needed.
+- Project graph building is linear in the number of edges (edge de-duplication, import traversal and package lookups no longer rescan everything); 50k import edges now build in about 0.1 s instead of 3.2 s, and 100k in about 0.25 s. Graph output is unchanged. `athena graph --node` and task-context expansion use a per-graph index.
+- Git metadata is collected with concurrent `git` processes, the `git --version` check runs once per process, and history is read once, bounded to the last 180 days / 2,000 commits. The contributor count in `model.json` (`git.contributorCount`) now counts authors in that window instead of the whole history.
+- Nested `.gitignore` matching only consults the path's own ancestor directories instead of every `.gitignore` in the project.
+- Analysis is staged and incremental: a stat-only walk, one content pass in which every new or changed file is read exactly once (hashing and all per-file detector work share the same bytes), then an aggregate stage that builds the model from cached per-file facts. Unchanged files are not read at all. The generated `model.json` is unchanged (guarded by a golden test against the 0.2.1 analyzer).
+- 20,000-file benchmark (Apple M-series, vs 0.2.1): warm `sync --check` 2.9 s → 0.50 s (×5.8), `sync --check` after a one-file change 2.9 s → 0.49 s, cold `init` 3.5 s → 2.3 s; peak memory lower in every scenario (warm sync 195 → 162 MB). 200,000 files: warm `sync --check` 46 s → 4.1 s, cold `init` 51 s → 40 s, peak memory 730 → 589 MB (init).
+- File text is no longer cached without limit during analysis: a 64 MB byte-budgeted LRU serves the rare aggregate-stage lookup, and text is dropped as soon as a file's facts are computed.
+- Sync planning goes through one scheduler per project (`src/services/scheduler.ts`): at most one analysis runs at a time, requests that arrive meanwhile share a single follow-up run, and new file changes can cancel a plan that is still in progress (planning is read-only). The file watcher, the local server (`POST /api/sync/check`, review, re-plans after edits) and the MCP server use it, so concurrent checks no longer start concurrent full analyses; applying a proposal and a full re-analysis from the web UI never interleave with planning.
+- While `athena open` (or another watcher) is running, a plan after file changes re-checks only the paths the watcher reported instead of walking the whole tree (about 265 → 170 ms for a one-file change in the 20k-file benchmark, in-process). It walks the whole tree on the first plan, after a `.gitignore`, `.athena/config.json` or `.git/info/exclude` change, a directory add/delete, a watcher error, when the project contains symbolic links, and at least every 5 minutes.
+- `athena status` (and the server's status, the MCP `get_project_changes` tool) no longer walks the tree: it stats the files in the cached index and asks Git for new files (`git ls-files`, `git status --porcelain=v2 -z`). 254 → ~140 ms on the 20k-file benchmark; ~0.85 s for 200k files. The output is unchanged; it falls back to walking when Git can't give the same answer (no Git or no index, `include` patterns, ignore rules changed since the last analysis, submodules, nested repositories, symlinked directories).
+- The server's status report is cached until the watcher reports a change (with a 30 s safety TTL, instead of a flat 3 s), and concurrent requests share one computation.
+
+### Changed
+
+- **The pre-commit hook checks what is being committed.** New `athena sync --check --staged` compares the `.athena/` knowledge as staged with what Athena generates from the code as staged, so untracked files (a scratch file, a local `.env`) and unstaged edits no longer block a commit, and a staged change reverted in the working tree still counts. It mirrors the index into `.athena/cache/staged/` (gitignored, updated incrementally): files that match the working tree are sparse stand-ins that reuse the last analysis's hashes and the facts cache, so only staged changes are read (20k files, warm: ~0.54 s vs ~0.44 s for the working-tree check). When `athena sync` already wrote a document that isn't staged, the output says which files to `git add`; JSON output has `staged`, `inSync`, `stale` and per-document details. Exit code 3 when `.athena/` is not in the index; 2 when the index has unresolved conflicts. `athena git-hook install` writes the new command (re-run it to update an existing hook; `athena git-hook status` shows `staged: false` and a hint for old hooks), and the suggested husky/lefthook line is now `npx --no-install athena sync --check --staged`.
+- The manifest detector is split into one module per ecosystem (`src/core/analyzer/detectors/manifests/`); `model.json` output is byte-identical.
+- Files modified within 2 seconds of the file index being written are re-read on the next run instead of trusted by size and mtime (Git's "racily clean" rule), so a same-size edit in the same clock tick is never missed.
+- The local server is split into route modules (`src/server/routes/*`) sharing one server context; routes, authentication, Host/Origin checks, security headers, CSP and rate limiting are unchanged.
+- `GET /api/sync` returns the proposal without `documents[].diff` (reasons, changed and preserved sections, additions/deletions and `diffTruncated` are still included). New `GET /api/sync/:doc[?planId=…]` returns one proposed document's diff; the id must be a knowledge document in the current proposal (404 otherwise, 409 when `planId` is stale). `POST /api/sync/check` still returns the full plan.
+- A corrupted `model.json` now gives a clear error with a hint (`model.json is corrupted (…)`, run `athena analyze`) instead of an internal error when starting a security scan from the web UI.
+- Test, source, auth, API and schema path patterns now come from one module (`src/core/patterns.ts`). `athena review` recognizes more test layouts (`integration_tests/`, `androidTest/`, `test_driver/`, `*_test.dart`), and change impact recognizes the same test files as review plus test runner configs.
+- New per-file facts cache in `.athena/cache/v1/` (gitignored; `cache/` is added to `.athena/.gitignore`, also for existing projects). Facts are keyed by content hash and discarded automatically when detector versions or the `ignore`/`include`/`maxFileBytes` settings change. Safe to delete; `athena clean` removes it with `.athena/`.
+- `state.json` schema 2: the file index moved to `.athena/cache/v1/files.json` (full SHA-256 hashes), so `state.json` stays small regardless of repository size. Version-1 files are migrated automatically on first read; older Athena versions will treat a v2 `state.json` as corrupted and rebuild it.
+- `athena init` creates the machine-local fingerprint salt (`.athena/local.json`) together with `.athena/`, so secret-finding fingerprints in the first `model.json` already use the project's stable key.
+
 ## 0.2.1 — 2026-09-30
 
 Security release. Upgrading is recommended for everyone. After upgrading, run `athena sync` once (the `security.md` format changed) and, if you use the pre-commit hook with `--review`, run `athena git-hook install --review` again so it reviews staged changes.

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
@@ -104,6 +138,7 @@ Apply updates to 2 documents? [y/N]
 - **Your edits are still safe.** Developer-edited sections are preserved and listed. Applying is refused if a document changed after the proposal was made.
 - When files change but no knowledge is affected, only the local index is refreshed.
 - `athena sync --check` exits with 1 when knowledge is out of date, which is useful in CI or a pre-commit hook (see [Use in CI and git hooks](#use-in-ci-and-git-hooks)). Change hotspots come from Git history and move with every commit, so the check ignores them; `athena sync` still refreshes them.
+- `athena sync --check --staged` checks what a commit would contain instead of the working tree: the `.athena/` knowledge as staged against the code as staged. Untracked files and unstaged edits don't count. This is what the pre-commit hook runs.
 - Ignore rules: defaults, root and nested `.gitignore` files, `.git/info/exclude`, and `.athena/config.json`.
 
 ## Watching what agents do
@@ -192,16 +227,22 @@ A complete workflow is in [examples/github-workflow.yml](examples/github-workflo
 ```text
 $ athena git-hook install
 ✓ Installed the pre-commit hook (knowledge check) at .git/hooks/pre-commit
-Commits are blocked when .athena/ knowledge is out of date. Teammates without Athena installed are not blocked.
-Using husky, lefthook or pre-commit? Add `npx --no-install athena sync --check` to its pre-commit config instead.
+Commits are blocked when the staged .athena/ knowledge is out of date for the staged code (untracked and unstaged files are ignored). Teammates without Athena installed are not blocked.
+Using husky, lefthook or pre-commit? Add `npx --no-install athena sync --check --staged` to its pre-commit config instead.
 
 $ git commit -m "Add refunds"
-Proposed: api.md, security.md
-Knowledge is out of date. Run `athena sync` to review and apply.
-athena: commit blocked: .athena/ knowledge is out of date. Run `athena sync`, stage .athena/ and commit again (or skip once with `git commit --no-verify`).
+  ~ api.md       endpoints
+  ~ security.md  attack-surface
+Staged knowledge is out of date for the staged code. Run `athena sync`, then stage .athena/.
+athena: commit blocked: staged .athena/ knowledge is out of date. Run `athena sync`, stage .athena/ and commit again (or skip once with `git commit --no-verify`).
 ```
 
-- `athena git-hook install --review` also runs `athena review` and blocks commits that add possible secrets or env files. It checks the whole working tree (staged, unstaged and untracked files that aren't ignored), not only what is staged.
+- The hook checks the commit, not the working tree: an untracked scratch file, a local `.env` or an unstaged edit never blocks a commit, and a change you staged and then reverted in the working tree still counts. If `athena sync` already updated a document but it isn't staged, the output says which files to `git add`.
+- The check mirrors the index into `.athena/cache/staged/` (gitignored). Files that match the working tree are stand-ins that reuse the last analysis and the facts cache, so only staged changes are read; the directory is updated incrementally and is safe to delete. Submodules are checked as they are in the working tree. Local env files that aren't committed (such as `.env`) are machine-local: the check accepts staged knowledge written with or without them.
+- Knowledge generated by `athena sync` describes the working tree. If untracked files that are not gitignored change it (a new route in a file you don't commit), the staged check reports the difference; commit, ignore or stash those files before syncing.
+- Hooks installed by earlier versions check the working tree; `athena git-hook status` points them out and `athena git-hook install` updates them.
+
+- `athena git-hook install --review` also runs `athena review --staged` and blocks commits that add possible secrets or env files. Like the knowledge check, it only looks at what is staged.
 - The hook is a `#!/bin/sh` script in the directory Git actually uses (`git rev-parse --git-path hooks`), so `core.hooksPath` and linked worktrees work. For a project in a subfolder of the repository, the hook runs Athena there.
 - If `athena` is not on `PATH`, the hook prints a note and lets the commit through, so it never blocks teammates who don't use Athena.
 - **An existing pre-commit hook is kept.** If it is a shell script, Athena adds its block between `# athena:start` and `# athena:end` right after the shebang, so it runs before your own commands. Athena refuses to touch hooks written in other languages and hooks it recognizes as managed by husky, lefthook or pre-commit (from `core.hooksPath` or the hook's contents), and prints the line to add instead.
@@ -211,7 +252,7 @@ athena: commit blocked: .athena/ knowledge is out of date. Run `athena sync`, st
 
 ```bash
 # .husky/pre-commit
-npx --no-install athena sync --check
+npx --no-install athena sync --check --staged
 ```
 
 ```yaml
@@ -219,7 +260,7 @@ npx --no-install athena sync --check
 pre-commit:
   commands:
     athena:
-      run: npx --no-install athena sync --check
+      run: npx --no-install athena sync --check --staged
 ```
 
 ### Example project
@@ -242,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-BKW7G4I5.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import {
+  listAgents
+} from "./chunk-QLW657NT.js";
+import {
+  readRecentEvents,
+  summarizeSessions
+} from "./chunk-65TSRDQ3.js";
+import {
+  c,
+  dim,
+  heading,
+  isJson,
+  json,
+  line,
+  relativeTime,
+  sym
+} from "./chunk-Z6QWMJLK.js";
+import {
+  requireProjectRoot
+} from "./chunk-XFN7UZCS.js";
+import "./chunk-KBO7XRBW.js";
+import "./chunk-JCGDR4UV.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-XW3MLHI2.js";
+import "./chunk-EUPETUWA.js";
+
+// src/cli/commands/activity.ts
+var STATE_COLOR = {
+  ANALYZING: c.cyan,
+  PLANNING: c.magenta,
+  CODING: c.blue,
+  TESTING: c.yellow,
+  REVIEWING: c.cyan,
+  SUCCESS: c.green,
+  IDLE: c.dim
+};
+async function activityCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  const limit = Math.min(Math.max(Number(opts.limit ?? 30) || 30, 1), 500);
+  const all = await readRecentEvents(root, 500);
+  const events = (opts.agent ? all.filter((e) => e.agent === opts.agent) : all).slice(-limit);
+  if (isJson()) {
+    json({ events, sessions: summarizeSessions(all) });
+    return;
+  }
+  heading("AI Agent Activity");
+  line();
+  if (!events.length) {
+    const agents = await listAgents(root);
+    const reporting = agents.filter((a) => a.activityObservation === "hooks");
+    line(dim("No agent activity recorded yet."));
+    line(dim(reporting.length ? `Hooks are installed for: ${reporting.map((a) => a.name).join(", ")}. Events appear once an agent runs in this project.` : "Install hooks with `athena agents add claude-code` (or cursor, codex, copilot, gemini-cli) to record agent activity."));
+    return;
+  }
+  for (const e of events) {
+    const time = new Date(e.ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit", hour12: false });
+    const color = STATE_COLOR[e.state] ?? ((s) => s);
+    line(`${dim(time)}  ${color(sym.dot)} ${c.bold(e.agent)} ${dim("\xB7")} ${e.message}`);
+  }
+  line();
+  for (const s of summarizeSessions(all).slice(0, 5)) {
+    line(dim(`${s.agent} ${s.session ? `(${s.session.slice(0, 8)})` : ""}: ${s.events} events, last ${relativeTime(s.lastEventAt)}`));
+  }
+  line(dim("Only hook-reported tool use is shown. Athena cannot see agent reasoning."));
+}
+export {
+  activityCommand
+};
+//# sourceMappingURL=activity-BKW7G4I5.js.map

package/dist/agents-DFSNEOP5.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import {
+  configureAgents,
+  listAgents,
+  removeAgents
+} from "./chunk-QLW657NT.js";
+import "./chunk-65TSRDQ3.js";
+import {
+  c,
+  dim,
+  heading,
+  isJson,
+  json,
+  line,
+  ok,
+  sym
+} from "./chunk-Z6QWMJLK.js";
+import {
+  requireProjectRoot
+} from "./chunk-XFN7UZCS.js";
+import "./chunk-KBO7XRBW.js";
+import "./chunk-JCGDR4UV.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-XW3MLHI2.js";
+import "./chunk-EUPETUWA.js";
+
+// src/cli/commands/agents.ts
+async function agentsListCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  const rows = await listAgents(root);
+  if (isJson()) {
+    json(rows);
+    return;
+  }
+  heading("AI Agent Integrations");
+  line();
+  for (const r of rows) {
+    const icon = r.configured ? c.green(sym.dot) : c.dim(sym.ring);
+    line(`${icon} ${c.bold(r.name)} ${dim(`(${r.id})`)} \u2014 ${r.configured ? "configured" : "not configured"}${r.detectedInProject ? dim(` \xB7 detected: ${r.evidence.join(", ")}`) : ""}`);
+    line(`  ${dim(r.note)}`);
+  }
+  line();
+  line(dim('"Configured" means Athena instruction files are in place. Agents with hooks also report their tool use \u2014 see `athena activity`.'));
+}
+async function agentsAddCommand(names, opts) {
+  const root = await requireProjectRoot(opts);
+  const results = await configureAgents(root, names);
+  if (isJson()) json({ ok: true, agents: results });
+  else for (const r of results) ok(`${r.id}: ${r.files.map((f) => `${f.path} (${f.action})`).join(", ")}`);
+}
+async function agentsRemoveCommand(names, opts) {
+  const root = await requireProjectRoot(opts);
+  const removed = await removeAgents(root, names);
+  if (isJson()) json({ ok: true, removed });
+  else ok(removed.length ? `Removed Athena integration from ${removed.join(", ")}` : "Nothing to remove");
+}
+export {
+  agentsAddCommand,
+  agentsListCommand,
+  agentsRemoveCommand
+};
+//# sourceMappingURL=agents-DFSNEOP5.js.map

package/dist/ai-ASL4FFQ7.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import {
+  aiStatus,
+  buildEnrichPayload,
+  enrich
+} from "./chunk-RXNRMIZP.js";
+import {
+  c,
+  dim,
+  heading,
+  isJson,
+  json,
+  line,
+  spinner,
+  sym,
+  warn
+} from "./chunk-Z6QWMJLK.js";
+import {
+  requireProjectRoot
+} from "./chunk-XFN7UZCS.js";
+import "./chunk-KBO7XRBW.js";
+import "./chunk-PVCIGUIT.js";
+import "./chunk-JCGDR4UV.js";
+import "./chunk-FQEGEVLY.js";
+import "./chunk-2DY4PUR4.js";
+import "./chunk-IQQBAWSM.js";
+import "./chunk-AD4OZCU2.js";
+import "./chunk-EUPETUWA.js";
+
+// src/cli/commands/ai.ts
+var CONSENT_SOURCE = { env: "ATHENA_AI_CONSENT", local: ".athena/local.json", user: "user config" };
+async function aiStatusCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  const status = await aiStatus(root);
+  if (isJson()) {
+    json(status);
+    return;
+  }
+  heading("AI providers");
+  line();
+  for (const w of status.warnings) warn(c.yellow(w));
+  if (status.warnings.length) line();
+  for (const p of status.providers) {
+    const icon = p.availability.ok ? c.green(sym.ok) : c.dim(sym.ring);
+    line(`${icon} ${c.bold(p.name)}${p.selected ? c.cyan("  (selected)") : ""}`);
+    line(`    ${dim(`${p.remote ? "sends data to" : "runs locally at"} ${p.availability.endpoint} \xB7 default model ${p.defaultModel}`)}`);
+    if (!p.availability.ok) line(`    ${dim(p.availability.reason ?? "")}`);
+  }
+  line();
+  line(`Consent to send project knowledge: ${status.consent ? c.green(`granted (${CONSENT_SOURCE[status.consentSource ?? "env"]})`) : c.yellow("not granted")}`);
+  line(dim("Athena never needs AI: analysis, sync, context and MCP are deterministic. AI only produces INFERRED suggestions you review."));
+  line(dim('Configure in .athena/config.json \u2192 "ai": { "provider": "ollama" } for a fully local setup.'));
+  line(dim("Endpoint (baseUrl) and consent are machine-local only: ATHENA_AI_BASE_URL / ATHENA_AI_CONSENT=1, .athena/local.json, or ~/.config/athena/config.json."));
+}
+async function aiEnrichCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  const docs = opts.docs?.split(",").map((d) => d.trim()).filter(Boolean);
+  const payload = await buildEnrichPayload(root, { docs });
+  if (!isJson()) {
+    heading("AI enrichment");
+    line();
+    for (const w of payload.warnings) warn(c.yellow(w));
+    if (payload.warnings.length) line();
+    line(`Provider:  ${c.bold(payload.provider.name)} ${dim(`(${payload.model})`)}`);
+    line(`Sends to:  ${payload.remote ? c.yellow(payload.endpoint) : c.green(`${payload.endpoint} (local)`)}`);
+    line(`Content:   ${payload.documents.join(", ")} ${dim(`(${payload.chars} characters, redacted knowledge only \u2014 no source code)`)}`);
+    line();
+  }
+  if (opts.dryRun) {
+    if (isJson()) json({ ...payload, provider: payload.provider.id });
+    else line(dim("Dry run \u2014 nothing was sent."));
+    return 0;
+  }
+  const sp = spinner(`Asking ${payload.provider.name}...`);
+  let result;
+  try {
+    result = await enrich(root, { docs, consent: opts.consent, signal: opts.signal });
+    sp.succeed(`Suggestions written to .athena/${result.file}`);
+  } catch (err) {
+    sp.stop();
+    throw err;
+  }
+  if (isJson()) json(result);
+  else {
+    line();
+    line(result.markdown.split("\n").slice(0, 40).join("\n"));
+    line();
+    line(dim(`Full suggestions: .athena/${result.file} (gitignored). These are INFERRED \u2014 nothing was added to your knowledge base.`));
+  }
+  return 0;
+}
+export {
+  aiEnrichCommand,
+  aiStatusCommand
+};
+//# sourceMappingURL=ai-ASL4FFQ7.js.map

package/dist/analyze-ZY3MXBOI.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import {
+  parseAgentsOption,
+  printSummary,
+  runWithProgress,
+  summarize
+} from "./chunk-XDCKZ5TV.js";
+import {
+  printHeader
+} from "./chunk-SHKXELUX.js";
+import {
+  isJson,
+  json
+} from "./chunk-Z6QWMJLK.js";
+import {
+  requireProjectRoot
+} from "./chunk-XFN7UZCS.js";
+import "./chunk-KBO7XRBW.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-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-XW3MLHI2.js";
+import "./chunk-EUPETUWA.js";
+
+// src/cli/commands/analyze.ts
+async function analyzeCommand(opts) {
+  const root = await requireProjectRoot(opts);
+  const agents = parseAgentsOption(opts.agents, false);
+  printHeader();
+  const result = await runWithProgress(root, { mode: "analyze", force: opts.force, agents, signal: opts.signal });
+  if (isJson()) json(summarize(result, root, false));
+  else printSummary(result, false, "analyze");
+}
+export {
+  analyzeCommand
+};
+//# sourceMappingURL=analyze-ZY3MXBOI.js.map