{"_id":"@aprimediet/memory","name":"@aprimediet/memory","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aprimediet/memory","version":"1.0.0","type":"module","description":"Persistent, self-managing project & global memory for the pi coding agent.","keywords":["pi-package"],"pi":{"extensions":["./index.ts"]},"peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-agent-core":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","typebox":"*"},"optionalDependencies":{"better-sqlite3":"^11.0.0"},"gitHead":"8fb87169dbb5b0ddb9934676e5e5abd22b45c6c4","_id":"@aprimediet/memory@1.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-r1RR9335/Lq2BRU6lTE3jwJwyeojfkhcwrzvh5f8CSjqz/fLPBVJ7JrJxjfpEILjwyPU6WHmLpUm2F7l+Ev33Q==","shasum":"2e2f48c7119ce00b6d8ed656011f123edd633cad","tarball":"https://registry.npmjs.org/@aprimediet/memory/-/memory-1.0.0.tgz","fileCount":13,"unpackedSize":65958,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC1G05zgtW0G4AsfqHulozwGMTDqI/XEScmtxQKOhb3AQIgOnX3G03XnCsjURiisyq31673qzJdZ+rQxcBI2m+UhR8="}]},"_npmUser":{"name":"aditya.prima","email":"aprimediet@gmail.com"},"directories":{},"maintainers":[{"name":"aditya.prima","email":"aprimediet@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory_1.0.0_1782397134253_0.6860233744051123"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-25T14:18:54.070Z","1.0.0":"2026-06-25T14:18:54.381Z","modified":"2026-06-25T14:18:54.658Z"},"maintainers":[{"name":"aditya.prima","email":"aprimediet@gmail.com"}],"description":"Persistent, self-managing project & global memory for the pi coding agent.","keywords":["pi-package"],"readme":"# @aprimediet/memory\n\nPersistent, self-managing memory for the [pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). Remembers durable facts, decisions, and progress across sessions — per **project** and **globally** — decides on its own what is worth saving, restores context at session start, and prunes stale memory. Inspired by claude-mem, but deliberately **process-per-call** (no resident worker/daemon).\n\n## Storage model — clean working tree\n\nThe only thing written into your working tree is a single identifier file, `<cwd>/.pi/<project-id>.md`. **Every** memory artifact (entries, index, thoughts, db, config) lives globally, keyed by that project id:\n\n```\n<cwd>/.pi/<project-id>.md            ← the ONLY artifact in your working tree (a pointer)\n\n~/.pi/projects/<project-id>/          ← everything else, global\n  project.json                        metadata: id, name, paths seen, created, lastSeen\n  memory/\n    entries/*.md                      durable memory (source of truth, human-editable)\n    MEMORY.md                         generated index/digest\n  thoughts/<date>-<session>.md        per-session journals written by the distiller\n  queue/                              pending distillation jobs\n  memory.db                           optional SQLite FTS index (rebuildable)\n  memory.json                         optional per-project config override\n\n~/.pi/projects/_global/               cross-project (\"global\" scope) memory, same shape\n```\n\nThe project id is `<dir-slug>-<8charPathHash>`, recorded in the marker — so it is stable, and if you move the directory the marker keeps memory attached to the same project. Markdown files are the source of truth; `MEMORY.md` and `memory.db` are rebuildable accelerators.\n\n## What it does\n- **Intelligent capture (both modes).** The `memory_write` tool lets the agent save facts deliberately; a **background distiller** reads each session's transcript at the end and decides what durable knowledge to keep, deduping against tool-written entries.\n- **No forgetting across sessions.** At session start a compact digest of prior memory is injected as hidden context. The `memory_search` tool recalls more on demand (and bumps usage so recalled entries survive pruning).\n- **Visible timeline at the very start.** The moment pi loads (in the TUI), a claude-mem-style **memory timeline** for the project appears as a banner above the editor — before you type anything — with entries grouped by day (Today / Yesterday / date), each showing a time, type icon, and title, plus project/global counts. It clears once you start working; reshow it anytime with `/memory timeline`.\n- **Self-cleaning.** A cheap heuristic sweep runs every session (TTL on unused entries, supersede resolution, LRU cap); a periodic background model pass consolidates and removes stale or contradicted entries.\n- **Independent & configurable.** All background intelligence runs as a separate `pi` subprocess whose **model is user-selectable**.\n\n## Tools & command\n\n- `memory_write { scope, type, text, tags? }` — save a durable entry.\n- `memory_search { query, scope?, limit? }` — recall entries.\n- `memory_forget { id? | query?, scope? }` — soft-archive entries.\n- `/memory status | timeline | list [scope] | search <q> | prune | forget <id> | distill`\n\n## Configuration\n\nConfig resolves **per-project `~/.pi/projects/<id>/memory.json` → global default `~/.pi/agent/memory.json` → bundled default → env → flags**, re-read on every access. The bundled default is seeded to the global default path on first run. (Per-project config lives in the global dir too — nothing but the marker is written to your working tree.)\n\n```json\n{\n  \"enabled\": true,\n  \"model\": \"claude-haiku-4-5\",\n  \"capture\": \"both\",\n  \"injection\": { \"scope\": \"both\", \"digestMaxEntries\": 20 },\n  \"pruning\": { \"ttlDays\": 90, \"maxEntries\": 200, \"consolidateEverySessions\": 10 },\n  \"useFtsIndex\": false\n}\n```\n\n- Flags: `--memory-model <pattern>`, `--memory-disabled`, `--memory-capture <tool|background|both>`.\n- Env: `MEMORY_MODEL`, `MEMORY_DISABLED=1`.\n- `capture`: `tool` (manual only), `background` (distiller only), `both`.\n- `useFtsIndex`: enable SQLite FTS search (requires the optional `better-sqlite3` dependency; falls back to file keyword scan when absent).\n\n## Install\n\nAdd the package to your project's `.pi/settings.json`:\n\n```json\n{ \"packages\": [\"../extensions/memory\"] }\n```\n\n## Notes & boundaries\n\n- **Your working tree only ever gets `<cwd>/.pi/<project-id>.md`** — a tiny, stable pointer. It is safe to commit (keeps the id consistent across clones) and safe to delete (recreated on next run). All actual memory is global and private to your machine; nothing project-specific is written into the repo.\n- **Secrets are never stored** — the distiller prompts forbid it and entry files are written `0o600`. Still, review project memory before committing.\n- The background distiller is **deferred**: `session_shutdown` enqueues a job and the next session drains the queue, so shutdown is never blocked. A failed distiller leaves the job for retry and never affects the host session.\n- Disable entirely with `--memory-disabled` / `MEMORY_DISABLED=1` / `\"enabled\": false`.\n","readmeFilename":"README.md","_rev":"1-d1ed4cbcea5e69a9706ef35a7bb65fca"}