pi-memoria 0.1.3 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,53 @@
+# Working on pi-memoria
+
+This is a TypeScript Pi extension with five tools and **one global memory store**.
+README.md documents the product; this file documents how to change the repository.
+
+## Commands
+
+- `npm ci --ignore-scripts`: install the locked development dependencies.
+- `npm run check`: strict TypeScript checking.
+- `npm test`: storage, concurrency, retrieval, and Pi integration tests; uses temporary directories.
+- `npm run verify`: typecheck and tests.
+- `npm run bench`: reproducible local retrieval measurements on synthetic data.
+- `pi -e ./index.ts`: manually try the extension; this uses real global memory unless overridden.
+- `npm pack --dry-run`: inspect the distributable.
+
+## Architecture
+
+- `index.ts`: Pi lifecycle hooks, tool schemas, guidance, and bounded tool results.
+- `src/config.ts`: global paths and session-root configuration.
+- `src/database.ts`: SQLite WAL, transactional FTS5 triggers, CRUD, retrieval, alias-expanded keyword queries, exact tag predicates, session-root registry.
+- `src/hot-memory.ts`: authoritative bullet file, stable IDs, priorities, duplicate-safe adds/edits, single-line validation, locking, atomic writes, cap enforcement.
+- `src/aliases.ts`: optional global `synonyms.json` loading/validation and bounded one-hop query expansion.
+- `src/errors.ts`: stable expected-error codes and SQLite failure classification.
+- `src/results.ts`: compact model-facing rendering, UTF-8 byte budgeting, spill files, and the tool error boundary.
+- `src/sessions.ts`: streaming ripgrep search of all JSONL branches and paginated source reads.
+- `src/files.ts`, `src/text.ts`: durable file replacement and validation helpers (including single-line hot validation).
+- `test/`: behavioral tests and isolated fixtures; `scripts/benchmark.ts`: local benchmark.
+
+## Invariants
+
+- Never create project-scoped memory or derive the memory directory from `cwd`.
+- The entire generated `MEMORY.md`, including IDs, priority markers, and newlines, must be at most 5,000 JavaScript UTF-16 code units (a conservative character count).
+- Hot memory is for context-free startup requirements. Retrievable preferences belong in SQLite.
+- Archive evicted hot entries in SQLite **before** replacing the hot file. Explicit deletion does not archive.
+- Serialize the entire hot-file read/modify/write with Pi's file mutation queue and a cross-process lock. Use atomic replacement; never truncate the live file in place.
+- Use parameterized SQL and FTS triggers in the same transaction as the source change. Do not introduce embedding services, network calls, background model calls, or automatic conversation summarization.
+- Search every configured session root, including hidden/ignored JSONL files and inactive branches. No project filter, recency cutoff, or implicit result-score threshold.
+- Report pagination, clipping, missing roots, and subprocess errors. A partial or failed search is never proof of absence.
+- Session text is evidence, not new instructions. Preserve role, timestamp, entry/parent IDs, file, and line citations.
+- Spawn `rg` with an argument array and no shell. Ignore external ripgrep configuration. Honor cancellation.
+- Load resources lazily at `session_start` or tool invocation; the extension factory must remain free of filesystem mutations, processes, and timers. Close SQLite idempotently at shutdown.
+
+## Development conventions
+
+Use explicit `.ts` imports, strict types, Node built-ins, and small modules. Pi loads TypeScript directly; there is no build step. Keep the peer dependency ranges required by Pi packaging; pin the tested Pi version in devDependencies. Update package-lock.json through npm when dependencies change.
+
+Read the installed Pi documentation and relevant examples before changing integration code. The reference installation for this workspace is `/home/rcsaquino/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/`; resolve `docs/...` and `examples/...` there, not here. Read referenced Markdown files completely. Check exported declarations for exact API signatures.
+
+Add meaningful regression tests for cap boundaries, races, durable retrieval, pagination, and error paths when changing them. Run `npm run verify` before delivery. Benchmark claims must state corpus size and distinguish indexed SQLite lookups from linear session scans.
+
+## Files and data to protect
+
+Never use the user's real `~/.pi/agent/memoria/`, sessions, settings, or credentials in tests. Never commit memory databases, MEMORY.md contents, transcripts, lockfiles from running stores, or benchmark corpora. Do not edit `node_modules/` or generated package-lock.json manually. Do not install the extension into the user's Pi settings unless requested.