Persistent memory for Pi. Learns from your sessions, corrects itself when wrong, and gets smarter over time.
v2.0.0 · Pi 0.85.1 · Node ≥22
Remendra learns automatically from your Pi sessions — no commands needed. It extracts facts, decisions, constraints, and procedures, then puts the right memories back in context when you need them. Memories survive across sessions, branches, and compactions.
If a memory is wrong, you correct it. Everything that depended on the wrong memory gets fixed too — automatically, in one transaction. No stale knowledge accumulating silently.
pi install @yoda.digital/pi-remendraRemendra shows setup guidance on first run automatically.
Alternative install methods
From git (latest development):
pi install git:github.com/yoda-digital/pi-remendraFrom a local checkout:
pnpm install --frozen-lockfile
pnpm build
pi install /absolute/path/to/pi-remendraRemendra works automatically — it learns from every session with no intervention. You can also interact with it directly:
/remendra search migration # find what it knows
/remendra remember Always back up first # teach it something
/remendra correct 42 Back up AND verify # fix a wrong memory
/remendra why 42 # see where a memory came from
/remendra doctor # health check
/remendra settings # view configuration
For typed claims, pass JSON: /remendra remember {"kind":"constraint","text":"Always back up before migrating production."}.
The recall tool is available to the agent automatically. Use /remendra help all for the full command reference.
How it works
The extension hooks into Pi's lifecycle:
- Ingestion. New session entries are converted to source records with SHA-256 content hashes and stored in SQLite.
- Background learning. After the agent settles, an observer model extracts structured claims from unprocessed source chunks. Each claim carries evidence: exact character spans into the stored source text. At most 4 batches per settled turn, 2 attempts per batch.
- Context compilation. Before each agent turn, Remendra compiles a memory packet. FTS5 matches the current query against stored claims. Results are ranked by search score and claim-type priority (constraints rank above hypotheses). The packet fits within a measured token budget and includes provenance metadata.
- Corrections. When you correct a memory, the old claim is superseded, its evidence spans are retired, dependent claims are invalidated recursively, and the replacement is recorded with its own evidence.
Memories you create with /remendra remember are project-scoped by default. Observer-extracted claims start at lineage scope (current session branch) and are auto-promoted to project scope at session end if they are verified and non-hypothetical. Accepting, pinning, or correcting a lineage claim also promotes it immediately. You can still promote or scope memories manually with /remendra promote ID project. User-scoped memories persist across projects when includeUser is enabled.
Auto-promotion is configurable: autoPromote: "full" (default), "user-actions" (only on accept/pin/correct), or "off" (old behavior).
Default storage: ~/.pi/agent/pi-remendra/v2/. Override with PI_REMENDRA_HOME.
/remendra settings # view current config
/remendra settings {"observer":false} # pause background learning
/remendra settings {"mode":"shadow"} # compile without injecting
/remendra settings {"mode":"recall"} # disable learning entirely
/remendra settings {"contextMode":"policy"} # cache-stable injection (KV-friendly)
/remendra index-sessions # index all past Pi sessions for search
Full default config: example-config.json.
The daily token budget (default 80 000) limits how many tokens background learning can spend. Use /remendra budget to check.
If you run an OpenAI-compatible embedding endpoint:
/remendra settings {"embeddings":{"endpoint":"http://127.0.0.1:8000/v1/embeddings","model":"YOUR_MODEL"}}
/remendra embed
/remendra semantic database configuration
HTTPS required for remote endpoints. Loopback HTTP works. No model is downloaded automatically.
Per-claim compilation latency on 1 000 synthetic claims (warm cache, single process):
p50: 16 ms p95: 16 ms database: 2.5 MB
Run the benchmarks yourself:
pnpm benchmark:v2 # per-claim microbenchmark
node benchmarks/suite.mjs # smoke test suite
These are synthetic tests. Real performance depends on corpus size, query complexity, and provider latency. See docs/benchmark-results.md for methodology and limitations.
There are 50+ memory extensions for Pi. Here is an honest comparison with the most popular ones.
| Feature | Remendra | pi-memory | pi-hermes-memory | pi-memory-mem0 |
|---|---|---|---|---|
| Storage | SQLite + FTS5 | Markdown files | Markdown + SQLite | Mem0 backend |
| Search | FTS5 trigram + optional embeddings | qmd keyword/semantic/hybrid | FTS5 trigram + session search | Mem0 semantic |
| Background learning | Observer extracts typed claims | Exit summaries | Background review every 10 turns | Passive every-turn capture |
| Corrections | Transactional: supersede + invalidate dependents recursively | Overwrite | Category-based | Overwrite |
| Evidence provenance | Exact character spans into source text | None | None | None |
| Typed claims | 7 types with ranking weights | None | 6 categories | None |
| Procedure validation | 2-trial per-environment verification | None | SKILL.md export | None |
| Secret scanning | OpenAI, GitHub, AWS, Stripe, Slack, DB URIs, PEM keys | None | Injection/exfiltration detection | None |
| Conflict detection | Subject/predicate dispute flagging | None | None | None |
| Revision history | Full audit trail | None | None | None |
| Session history search | /remendra index-sessions |
No | Yes | No |
| KV cache stability | Policy-only mode option | Snapshot mechanism | Policy-only mode | N/A |
| CJK search | FTS5 trigram (3+ chars) | Via qmd | FTS5 trigram | Semantic |
| Node compatibility | Node 22+ (24 built-in, 22 via better-sqlite3) | Node 22+ | Node 22+ | N/A |
| Privacy | Fully local, nothing leaves disk | Fully local | Fully local | Cloud by default |
Where Remendra is stronger: self-correcting memories (fix one, dependents update automatically), evidence provenance with exact source spans, typed claims with ranking, procedure trial validation, conflict detection, full revision audit trail, comprehensive secret scanning, fully local privacy.
Where others are stronger: pi-memory is simpler and human-editable (plain markdown). pi-hermes-memory has native skill export (SKILL.md). pi-memory-mem0 has zero-effort semantic capture with no configuration.
Pick Remendra when you manage long-lived projects across many sessions and care about correction integrity — when you fix a wrong memory, everything that depended on it gets invalidated automatically. You want full provenance: every memory traces back to exact character offsets in the original conversation.
Pick something else when you want the simplest possible setup (pi-memory), cloud-backed semantic search (pi-memory-mem0), or native skill export (pi-hermes-memory).
Linux, Windows, macOS · Node 22+ (Node 24 uses built-in SQLite; Node 22 uses better-sqlite3) · Pi 0.85.1. CI runs the full test suite on all three platforms.
128 tests across 10 files: store operations, compilation, observer parsing, worker lifecycle, embeddings, cross-platform paths, concurrent SQLite access, sustained growth (2000+ claims), token estimation accuracy, and secret redaction patterns.
The validation document is the honest accounting of what has been tested and what has not.
Remaining gaps: live-provider extraction quality and multi-day retention have not been soak-tested with real providers.
pnpm build # tsup → dist/
pnpm typecheck # tsc --noEmit
pnpm lint # eslint
pnpm test # vitest
pnpm test:smoke # real Pi SDK smoke
pnpm benchmark:v2 # per-claim latencyEngineering notes · Validation · Benchmark methodology
MIT.