ai-raccoon-memory

Files (13)

• SKILL.md
• badger_store.py · scripts/
• memory_broker.py · scripts/
• memory_broker_hook.py · scripts/
• memory_context.py · scripts/
• memory_context_hook.py · scripts/
• memory_first_gate.py · scripts/
• memory_first_gate_hook.py · scripts/
• memory_first_gate_post_hook.py · scripts/
• memory_grade_hook.py · scripts/
• openrouter_client.py · scripts/
• query_pipeline.py · scripts/
• shell_parser.py · scripts/

SKILL.md (first lines)

# AiRaccoon Memory

## When NOT to Use

- A one-off lookup ("have we seen X before?") — run `query` and be done, no watch ritual, no write-back
- No docs directory to watch and no durable fact to write — the ritual adds ceremony, not value
- The memory-grade hook when you only need one answer — it is opt-in by env var; don't enable it for a single search

## 1. Watch-on-docs ritual (do this first)

On session start, run `get_watch_status(projectId)` for this project. If the docs directory
is not in the watched list, run `add_watch(projectId, <absolute path to docs>)` to mirror
it into memory. The watch starts `scanning` and settles to `healthy`; an already-watched path is
a no-op.

Also watch `.semantica/` (one-time per project): `mkdir -p .semantica`, then
`add_watch(projectId, <absolute path to .semantica>)`. Re-adding is a no-op; the durable
record lives in memory, so gitignore `.semantica/` in the consumer repo.

**CLI prerequisite (only when the watch errors):** `watching-disabled` or `path-outside-scope`
means the one-time per-install setup is missing (quote the `*` so the shell does not expand it):
`ai-raccoon watch scope add '<project-id|*>' <path>`, then
`ai-raccoon watch enable '<project-id|*>' true`. If the `memory_watch_*` tools are not listed at
all (older tool build on another machine), update the tool: `dotnet tool update -g arasz.ai-raccoon`.

## 2. Search-first workflow

Always pass `projectId` and `sessionId`. Pass your session id on every search. The server rejects a blank one and stores the value verbatim on the search row. Before web search, code search, or asking the user, run `query(projectId, sessionId, scope=all)` with 2-3 formulations. Try the exact phrase first, then keywords, then a plain restatement. Entries carry source paths. Cite them as evidence. Every reply carries `meta.correlationId`. Keep that id. You need it to grade the search or to record that you opened one of its files.

## 3. Escalation by result

- Decisive hit → use it; cite the source path.
- Partial hit → one targeted external search, then reconcile.
- No hit → search externally, then write the finding back with `add_memory` (source path included).

## 4. Write discipline

Durable facts only, one per entry, source included. Plain writes land in committed project
memory (`project:<id>`). For in-progress notes use workspace isolation:
`initialize_workspace` → `get_workspace_status` → `close_workspace(keep=[...])`
(or `["all"]` to promote everything; `discard_workspace` to drop). Promote durable
cross-project facts with `share_memory` — never automatically. `trigger_memory_cleanup` removes old
low-rated entries; shared entries are exempt.

## 5. Scopes and kinds

`scope=all` (default: shared + project), `scope=project`, `scope=shared` (the promotion tier only). Kind defaults to `both`. It runs the memory and code hybrids separately and returns both sections. `kind=memory` searches memory only. `kind=code` searches code only. Recording follows the request. Memory and both store the memory leg count and files. Code stores the code count with an empty file list. Code paths never enter the table.

## 6. Gotchas

- `add_memory` has **no `path` param** — the entry path is derived from its content.
- **Never pass `context`** unless workspace isolation is intended: it silently sets
  `scope='custom'`, invisible to project-scoped search.
- `embed_deferred_entries`: omit `limit` to process all pending entries.
- `delete_context` requires full access mode.
- When you open a file the search returned, call `set_memory_usage_record` with the same `correlationId`, the file path, and `servedRank` when you saw one. Rank is 1-based. Under `kind=both` a bare rank cannot name its section. That ambiguity is intentional, so send no section qualifier. Grade with `set_query_result_grade` (1-5) on the same id when you have a judgment.
- A `query` result (`kind=code` or `kind=both`) carrying a warning starting
  `code engine not configured` means its code section is FTS5 keyword matches only — semantic
  code hits are missing, not absent; don't read it as a complete answer. Tell the user, once
  per session, verbatim: run `ai-raccoon model set code default` (downloads and activates the
  default code embedding model, ~187 MB, one-off) — don't repeat the hint on later searches in
  the same session. Don't re-run the search hoping for vector results: nothing changes until
  that command runs.

## 7. Bulk ops

`ingest_file` / `ingest_directory` bulk-load files; `get_store_statistics` reports bank
size; `sync_to_cloud` exchanges snapshots with cloud storage when configured.

## 8. Per-prompt memory context (automatic)

This skill ships a hook that searches memory for you before the model sees each prompt. It
runs on Claude Code and Copilot CLI (`UserPromptSubmit` / `userPromptSubmitted`, entry
`scripts/memory_context_hook.py`) and in Hermes CLI sessions (`pre_llm_call`). It never runs
on pi. It is POSIX only: on Windows it stays silent and spawns nothing.

**When it fires.** Every prompt that passes pi's `shouldEnrich` gate (long enough, enough
distinct words, not a slash command or a control word like `continue`), in a project where
`.ai-badger/project-id` resolves and the `ai-raccoon` executable is found (`PATH` first, then
`~/.dotnet/tools/ai-raccoon`). A turn the harness wrote rather than a person (one that starts
with a marker in `INJECTED_PREFIXES`, such as `<task-notification>`, or holds only
`<system-reminder>` blocks) is skipped before any search or spawn. Leading reminder blocks in
front of your own text are stripped and the rest is gated as usual; a question whose first line
is a pasted notification is skipped for that turn. Each run spawns the bare `ai-raccoon` binary as a proxy, once,
and sends every search over that one session. The hook never reads the ai-raccoon token; the
proxy does the identity proof. If no serve is running, the proxy may start one, and that serve
outlives the hook under its own idle watchdog. When hits survive pruning, the hook injects a
"Memory context" block identical to pi's `toMemoryContext` output. Otherwise it injects
nothing, and the hook always exits 0. An expected failure (no proxy, a timeout, an error
reply) is silent. A missing or broken `memory_context.py`, or a defect in the hook's own
code, leaves one line in `~/.ai-badger/hook-errors.log` naming the exception type and where it
was raised, never the prompt; under Hermes the same line goes to Hermes's log as a warning.
If you opted in to third-party egress and a `dataPolicy` lock refuses it, one line naming the
locking config is written there too.

**Two modes.** Both inject the same block.

- *Pipeline*: runs only when you opt in — `AI_BADGER_ALLOW_THIRD_PARTY=1`, `OPENROUTER_API_KEY`
  set, `AI_BADGER_MEMORY_CONTEXT_PIPELINE` not `"0"`, and no ancestor `.ai-badger/config.json`
  declaring `dataPolicy` (a key alone does nothing). An OpenRouter model plans 2 to 6 retrieval queries, each is searched once, the
  Jev decisions endpoint scores the pooled hits, and pi's document-aware merge keeps the best
  five. The run's total is 90 s on Claude and Copilot, split into pi's stage limits
  (planner 15 s, each search 15 s, Jev 8 s). Under Hermes the total is 25 s and the stage
  limits shrink with it, so a planner that uses its whole share still leaves time for two
  full searches and the Jev stage. If the planner fails, the run falls back to one search on
  the prompt.
- *Single search*: every other case. One search on the prompt, capped at 5 s. Nothing leaves
  the machine except the call to the local proxy.

**What leaves the machine.** Only in pipeline mode, and only to OpenRouter: the gated prompt
(the planner's input, and its first 32 000 characters in each Jev request), and for up to 48
pooled hits their file path, kind and a 500-character excerpt of memory *and source code*.
The key is read from the environment only and is never logged or written anywhere. Without
the opt-in everything but the ai-raccoon search stays local; a project that commits
`"dataPolicy": "local-only"` keeps it local whatever a developer's shell sets (its object form
can allow named company hosts, still only with the opt-in). An exported `AI_BADGER_PROJECT_ID`
that differs from the working directory's project id keeps the single local search. The full
inventory is `docs/reference/data-access.md` in the ai-badger repository.

From Arasz/ai-badger, MIT.

More from Arasz/ai-badger