pi-memoria 0.2.0 → 0.3.1

package/AGENTS.md

@@ -0,0 +1,110 @@
+# 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 and release the repository.
+
+## North star
+
+1. **Recall.** If it is in memory, we retrieve it. If it was said in any prior conversation, session
+   search finds it. Failing to retrieve something that exists is the only unacceptable outcome.
+2. **Speed.** Millisecond retrieval on the common path; no query that changes how the agent works.
+3. **No context bloat.** Only hot memory (≤ 5000 characters) is always loaded. Everything else is
+   retrieved on demand.
+
+## 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.
+- Do not commit or push changes without explicit user approval.
+
+## 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.
+
+## Releasing
+
+Start a release only when the user decides to bump the version. Tags, GitHub releases, and npm versions are public and are not cleanly removable.
+
+1. Bump `version` in `package.json`, then run `npm run verify`. A version-only bump does not change dependencies, so `package-lock.json` needs no update.
+2. Commit as `Release X.Y.Z` and push `main`.
+3. Create an annotated tag `vX.Y.Z` with the message `pi-memoria X.Y.Z` (the convention for `v0.2.0` and later) and push it with the commit:
+
+    ```sh
+    git tag -a vX.Y.Z -m "pi-memoria X.Y.Z"
+    git push origin main vX.Y.Z
+    ```
+
+4. Create the GitHub release after the tag exists. Publishing the release triggers
+   `.github/workflows/npm-publish.yml`, which checks the tag against `package.json`, runs
+   `npm run verify`, and publishes to npm. `gh` is installed and authenticated as
+   `rcsaquino`:
+
+    ```sh
+    gh release create vX.Y.Z --title "pi-memoria X.Y.Z" --notes-file - <<'EOF'
+    ...
+    EOF
+    ```
+
+    Keep notes factual: what changed, requirements, and limits. Do not restate the README.
+
+5. Watch the workflow and confirm the registry:
+
+    ```sh
+    gh run list --workflow npm-publish.yml --limit 4
+    npm view pi-memoria version dist-tags
+    ```
+
+    - The workflow authenticates with npm trusted publishing (OIDC). The trusted publisher
+      on npmjs.com must name the repository `rcsaquino/pi-memoria` and the workflow file
+      `npm-publish.yml`. The package's publishing access disallows traditional tokens,
+      so OIDC is the only automated publish path.
+    - The `files` field in `package.json` controls the tarball; inspect it with
+      `npm pack --dry-run` first.
+    - The registry can accept the tarball (`HTTP 202`, "being processed") and take a few
+      minutes to expose it. Confirm with `npm view` before reporting success.
+    - Fallback only if the workflow is unavailable: `npm publish` locally. Writes require
+      2FA, so it starts the npmjs web-auth flow and needs a real terminal or pseudo-TTY to
+      open the browser; without one it fails with `EOTP`. An automation token with 2FA
+      bypass also works.
+
+Only push tags, create releases, or publish to npm for a user-requested version bump.
+
+## 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.

package/README.md

@@ -1,224 +1,184 @@
+<!-- prettier-ignore -->
+<div align="center">
+
 # pi-memoria
 
-Long-term memory for [pi](https://pi.dev). Saves preferences, project context and
-past decisions as Markdown files, then retrieves relevant notes in later sessions.
+**Global memory for [Pi](https://github.com/earendil-works/pi): startup rules in `MEMORY.md`, durable facts in SQLite FTS5, and cited search across every past conversation.**
+
+[![GitHub release](https://img.shields.io/github/v/release/rcsaquino/pi-memoria?style=flat-square)](https://github.com/rcsaquino/pi-memoria/releases)
+[![Node.js >= 22.19](https://img.shields.io/badge/Node.js-%3E%3D22.19-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![MIT license](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
+
+[How it works](#how-it-works) • [Installation](#installation) • [Hot memory](#hot-memory) • [Tools](#tools) • [Configuration](#configuration) • [Performance](#performance) • [Support](#support-and-contact)
 
-Memory lives in your agent directory and follows you across projects. Search runs
-locally, with no database, embedding service or additional runtime dependencies.
-The agent can also search pi's saved conversations when a detail was never saved
-as a note.
+</div>
 
-## Install
+pi-memoria gives Pi one memory shared across every project: instructions that must apply from the first message go in a capped `MEMORY.md`, everything else in SQLite with FTS5, and past conversations stay searchable through ripgrep. Five tools, local storage only. No embeddings, no network calls, no background model work.
 
-Requires pi and Node.js **22.19.0 or later**.
+## Requirements
+
+- **Node.js 22.19+** (uses `node:sqlite`; tested on 22.19 and 24.20).
+- **Pi** with the current extension API (tested with 0.87.1), Node-based. Standalone/Bun builds are not validated with `node:sqlite`.
+- **ripgrep (`rg`) on PATH** for session search.
+
+## Installation
 
 ```sh
 pi install npm:pi-memoria
 ```
 
-Restart pi or run `/reload` to load the extension and its bundled skills.
-No configuration is required.
+Restart Pi or run `/reload`. To uninstall, run `pi remove npm:pi-memoria`; stored memory remains until you delete its directory.
 
-Alternatively, install a tagged release from GitHub:
+<details>
+<summary><strong>Install from a local checkout</strong></summary>
 
 ```sh
-pi install git:github.com/rcsaquino/pi-memoria@v0.2.0
+npm ci --ignore-scripts
+pi install /absolute/path/to/pi-memoria
 ```
 
-Use one installation method, not both.
+Keep the checkout in place: a local install references it directly. To try it without installing:
 
-## Use it
+```sh
+pi -e /absolute/path/to/pi-memoria/index.ts
+```
 
-Ask pi to remember something:
+</details>
 
-```text
-Remember that I use pnpm for personal projects and prefer tabs over spaces.
-```
+## How it works
 
-In a later session, relevant notes are added to the agent's context automatically.
-You can also ask directly:
+| Store | What belongs there | How it is retrieved |
+|---|---|---|
+| `MEMORY.md` | Instructions that must apply before any retrieval cue appears | Loaded at startup and refreshed before every user prompt |
+| SQLite + FTS5 | Preferences, facts, decisions, names, conventions | `memoria_search` |
+| Original Pi JSONL sessions | What was actually said, including old branches and pre-compaction messages | `memoria_sessions`, with file and line citations |
 
-```text
-What package manager do I use for personal projects?
-What did we decide about the deployment last week?
+"Start every sentence with `beep_boop`" belongs in hot memory: even a session starting with "Hello" must obey it. "The user likes apples" belongs in SQLite with tags such as `fruit` and `preferences`: a fruit recommendation supplies the retrieval cue.
+
+The model decides what to save and when to search; nothing is extracted automatically. Before saving, it searches for related memories, keeps unchanged facts, and edits existing ones when information changes. SQLite rejects repeated identical adds; differently worded paraphrases depend on the model's judgment.
+
+## Hot memory
+
+```md
+- [h_0123456789abcdef] [p=90] Start every sentence with beep_boop.
 ```
 
-Useful commands:
+Priority is **0–100** (default 50). The **entire file**, including IDs and newlines, must fit in **5,000 UTF-16 code units**, checked before every write. Content is single-line; CR, LF, U+2028, and U+2029 are rejected.
 
-| Command | Purpose |
-| --- | --- |
-| `/memoria` | Show store status and the briefing's size |
-| `/memoria search <query>` | Search saved notes |
-| `/memoria sessions <query>` | Search earlier conversations |
-| `/memoria topics` | Review notes and possible duplicates |
-| `/memoria doctor` | Check for consistency problems |
-| `/memoria paths` | Show storage locations |
+Duplicate adds reuse the existing bullet and consume no capacity. When space is needed, strictly lower-priority bullets are archived to SQLite first (`hot-archive`), then the file is atomically replaced; if that cannot free enough room, the write fails with the live file unchanged.
 
-Saving a fact and retrieving it are separate steps. Automatic recall searches
-existing notes; it does not turn every conversation into a memory. The agent
-saves a note when something is worth keeping.
+> [!WARNING]
+> Prefer the tools for edits. External edits can bypass the cap until the next load, and oversized content is never injected.
 
-## What gets remembered
+## Recall
 
-Memoria keeps three sources of context:
+Keyword search cannot infer every synonym, and session search has no recency or project filter. For "remember when" questions, search sessions and cite the original entries; follow `next_offset`/`next_text_offset`, and check `warnings` and `exhausted`. A partial or failed search is never proof of absence.
 
-- **A short briefing** (`MEMORY.md`): standing preferences and context included
-  in the system prompt. Limited to 5,000 characters by default.
-- **Topic notes** (`library/`): people, projects, decisions and other details
-  retrieved when relevant. Facts about the same subject accumulate in one file.
-- **Saved conversations**: read-only searches of pi's transcripts, with file and
-  line references so the agent can check the surrounding dialogue.
+## Tools
 
-For example, several preferences belong in `preferences/dietary-preferences.md`,
-not separate `likes-apples.md` and `likes-pears.md` files. Notes support aliases,
-links and superseded decisions. Renaming a note preserves its identity; merging
-notes requires an explicit request.
+| Tool | Purpose |
+|---|---|
+| `memoria_add` | Save a fact to SQLite or a startup rule to hot memory |
+| `memoria_edit` | Change content, tags, priority, or hot text by ID |
+| `memoria_delete` | Remove a memory by ID |
+| `memoria_search` | Search SQLite with keywords, modes, and exact tags |
+| `memoria_sessions` | Search or read original Pi session entries with citations |
 
-The default store is separate from the installed extension:
+Tool replies are compact; oversized results spill to a private `pi-memoria-result-*` file.
 
-```text
-~/.pi/agent/memoria/
-├── MEMORY.md
-├── config.json           # optional settings
-├── library/
-│   ├── people/
-│   ├── projects/
-│   └── preferences/
-├── .index/               # rebuildable search data
-└── .trash/               # recoverable deleted notes
+**Add a fact:**
+
+```json
+{"content":"The user likes apples.","tags":["fruit","preferences"]}
 ```
 
-If you set `PI_CODING_AGENT_DIR`, the store follows that directory. You can read
-and edit notes with a text editor; the index picks up changes automatically.
+**Add a hot rule:**
 
-## Configuration
+```json
+{"store":"hot","content":"Start every sentence with beep_boop.","priority":90}
+```
 
-Create `~/.pi/agent/memoria/config.json` to override defaults. For example, to
-add a project store and teach search an abbreviation:
+**Search memories:**
 
 ```json
-{
-  "projectRoot": ".pi/memoria-project",
-  "synonyms": { "k8s": ["kubernetes"] }
-}
+{"query":"k8s deploy","mode":"all","tags":["infrastructure"]}
 ```
 
-The primary store is user-wide. `projectRoot` adds an optional writable project
-store; `extraRoots` adds read-only stores. Reranking is off by default because
-it makes an additional model call per search.
+**Search sessions:**
+
+```json
+{"query":"deadline","role":"user","after":"2025-03-04","before":"2025-03-05"}
+```
+
+**Read a session entry:**
+
+```json
+{"action":"read","path":"/absolute/path/to/session.jsonl","line":42}
+```
+
+- **Add:** `store` is `long_term` (default) or `hot`; SQLite accepts `tags` and `source`. Identical content is reused with `created: false`; edits are the only way to change a fact. SQLite limits: 20,000 characters, 30 tags, 2,000-character source.
+- **Edit/delete:** pass an `id` (`m_` for SQLite, `h_` for hot) and only the fields to change. `expected_revision` or hot `expected_content` catches concurrent writes. Deletion never archives hot bullets or erases sessions.
+- **Search:** `memoria_search` searches SQLite only; hot `h_` entries are injected from `MEMORY.md` and cannot be searched or read by this tool. `mode` is `any` (default), `all`, `phrase`, or `literal`; a miss falls back to a literal scan and reports the mode used. `tags` match exactly and case-sensitively. `expand_aliases` adds `synonyms.json` terms for `any`/`all`. Read an SQLite memory with its `m_` ID; long content paginates via `text_offset`.
+- **Sessions:** decoded JSON is searched, including hidden, ignored, and inactive-branch files. Results carry path/line citations. `exhausted: true` means every accessible root was scanned without errors; warnings mean partial results, never absence.
+
+## Configuration
 
 <details>
-<summary>All configuration options</summary>
-
-| Key | Default | Meaning |
-|---|---:|---|
-| `rootDir` | `"$AGENT_DIR/memoria"` | Primary store. Supports `$AGENT_DIR`, `~/`, absolute and cwd-relative paths. |
-| `projectRoot` | `""` | Optional writable per-project store; empty disables it. |
-| `extraRoots` | `[]` | Additional **read-only** stores to search. |
-| `hotLimit` | `5000` | Hard cap for `MEMORY.md`, in characters. |
-| `snippetChars` | `280` | Body excerpt length per hit. |
-| `autoRecall` | `true` | Search the library on every user prompt. |
-| `autoRecallLimit` | `3` | Maximum notes injected per prompt. |
-| `autoRecallMinRatio` | `0.3` | Automatic hits must score at least this fraction of the strongest eligible hit; set to `0` to disable the relative cutoff. |
-| `autoRecallMinScore` | `1.4` | Score floor for auto-recall. |
-| `autoRecallMaxChars` | `2400` | Strict total character budget, including wrappers and transcript fallback. |
-| `autoRecallLastTurns` | `1` | Previous turns folded into the recall query. |
-| `autoRecallPriorWeight` | `0.4` | Weight of those previous turns versus the current prompt. |
-| `bodyCacheBytes` | `8388608` | In-memory body cache budget. |
-| `scanIntervalMs` | `2000` | Minimum interval between filesystem freshness scans. |
-| `watcherSettleMs` | `300` | Idle delay after a file event before refreshing (coalesces bursts). |
-| `exclude` | `[]` | Path fragments never indexed. |
-| `defaultCategory` | `"inbox"` | Folder for notes without a category. |
-| `topicMaxWords` | `6` | Longest topic name before falling back to the category. |
-| `topicMaxChars` | `8000` | Largest note before facts spill into a sibling file. |
-| `usageTracking` | `true` | Track hits/writes/last-used in `.index/usage.json`. |
-| `lastUsedWriteIntervalMs` | `21600000` | Refresh a note's `last_used` at most this often (6 h). |
-| `staleAfterDays` | `365` | `doctor` reports notes unused for longer. |
-| `promoteAfterWrites` | `3` | Suggest `memoria_hot` after this many writes with priority ≥ high. |
-| `dedupeThreshold` | `0.62` | Overlap above which two notes are reported as merge candidates. |
-| `relatedHits` | `3` | Related notes pulled into one result. |
-| `relatedBoost` | `0.35` | Score factor for those related notes. |
-| `synonyms` | `{}` | Inline synonym table (merged over `synonyms.json`). |
-| `synonymWeight` | `0.6` | Weight of synonym-expanded query terms. |
-| `timeHints` | `true` | Parse "last week"/"yesterday" in queries into a recency window. |
-| `searchCacheSize` | `32` | LRU entries for repeated identical searches (0 disables). |
-| `rerank` | `false` | Let the session model reorder recall candidates. |
-| `rerankModel` | `""` | Model id (`provider/model`); empty uses the session model. |
-| `rerankTopK` | `12` | Candidates shown to the reranker. |
-| `rerankTimeoutMs` | `2500` | Reranker budget before falling back to lexical order. |
-| `indexFormat` | `"auto"` | `auto` (binary above 20k notes), `json` or `binary`. |
-| `sessionSearch` | `true` | Search saved session transcripts at all. |
-| `sessionRoots` | `[]` | Extra transcript roots (searched before `<agent dir>/sessions`). |
-| `sessionFallback` | `true` | Search transcripts automatically when the library returns nothing. |
-| `sessionScanMs` | `1500` | Wall-clock budget for an explicit transcript search (the automatic fallback uses at most 400 ms). |
-| `sessionExcerptChars` | `400` | Context characters per transcript hit. |
-| `sessionCacheBytes` | `33554432` | In-memory budget for parsed transcripts. |
-| `sessionIncludeTools` | `false` | Include tool calls/results and compaction summaries by default. |
-| `sessionRipgrep` | `true` | Use a ripgrep prefilter to skip match-free transcripts when `rg` is available; without it the slower built-in scanner runs. |
+<summary><strong>Environment variables, aliases, and storage layout</strong></summary>
 
-</details>
+| Variable | Effect |
+|---|---|
+| `PI_CODING_AGENT_DIR` | Pi's agent directory; memoria defaults to its `memoria/` child |
+| `PI_MEMORIA_DIR` | Override the single global memory directory |
+| `PI_MEMORIA_SESSION_DIRS` | JSON array of additional absolute session roots |
 
-## Privacy and limits
+The optional `synonyms.json` next to `memoria.sqlite` maps terms for `any`/`all` searches. Built-ins are `k8s`→`kubernetes`, `db`→`database`, `repo`→`repository`, and `prefs`→`preferences`. Mappings are directional and one-hop; a malformed file is ignored whole with a warning.
 
-**Local storage does not mean model-private memory.** The briefing, recalled
-notes and returned transcript excerpts become part of the configured model's
-context. With a hosted model, that content is sent to its provider. Reranking
-also sends content to the configured model when enabled.
+```text
+~/.pi/agent/memoria/
+├── MEMORY.md
+├── memoria.sqlite
+├── synonyms.json
+└── backups/
+```
 
-- Notes are not encrypted, and memoria does not detect or redact credentials.
-  Do not store secrets.
-- Search is lexical (BM25 with aliases, synonyms, prefix and fuzzy matching),
-  not embedding-based. It can miss a paraphrase with no matching terms.
-- Recall is bounded. Relevant notes can be omitted by score or context limits;
-  transcript searches report `partial` when they run out of scan budget.
-- Reranking can reorder retrieved notes, not find notes that search missed.
-- Deletes move notes to `.trash/`. This is recovery, not secure erasure.
-- Writes use atomic file replacement, but separate pi processes are not
-  coordinated as concurrent writers. Keep backups.
+The default session root is `<agent-dir>/sessions`; roots Pi uses are remembered across projects. Changing `PI_MEMORIA_DIR` selects a different store without migrating the old one, project `cwd` is never used to choose it, and no data is sent over the network.
 
-## Backup and troubleshooting
+</details>
 
-Back up the store by copying `~/.pi/agent/memoria/` (or
-`$PI_CODING_AGENT_DIR/memoria/`). Notes are plain markdown, so a folder copy is
-the complete backup; `.index/` is derived and can be omitted.
+## Performance
 
-If recall misses an existing note, check `/memoria paths`, try a distinctive
-name or phrase, then run `/memoria reindex`. For duplicated subjects, use
-`/memoria topics` and ask the agent to consolidate the appropriate notes.
+<details>
+<summary><strong>Benchmark: 10,000 memories and 50,000 session entries (11.9 MB)</strong></summary>
 
-## Reference and development
+| Operation | Median | p95 |
+|---|---:|---:|
+| Selective SQLite FTS5 lookup | 0.093 ms | 0.119 ms |
+| Alias-expanded FTS5 lookup (`k8s` → `kubernetes`) | 0.123 ms | 0.158 ms |
+| Exact-tag filtered FTS5 lookup (10,000 matching rows) | 6.308 ms | 7.365 ms |
+| Literal SQLite full scan | 4.709 ms | 5.094 ms |
+| Hot-file refresh with locking | 0.148 ms | 0.249 ms |
+| Session match near the end of the corpus | 26.776 ms | 34.777 ms |
+| Absent session term, complete scan | 4.325 ms | 5.172 ms |
 
-The [reference guide](https://github.com/rcsaquino/pi-memoria/blob/main/docs/reference.md)
-covers all tools and commands, note format, scopes, session search, backup
-semantics, briefing validation and benchmark commands. It follows the current
-checkout, which may be ahead of the npm release.
+`npm run bench` recreates this synthetic corpus in a temporary directory. Warm-cache medians on Linux, Node 24.20, Ryzen 5 7500F, including `rg` startup. Indexed lookups stay fast; scans grow with corpus size. Not a performance guarantee.
 
-To work on the extension from a clone:
+</details>
+
+## Development
 
 ```sh
-npm install
-npm run typecheck
-npm test
-npm run eval
+npm ci --ignore-scripts
+npm run verify
 npm run bench
-pi -e ./index.ts
 ```
 
-No build step is needed. See
-[AGENTS.md](https://github.com/rcsaquino/pi-memoria/blob/main/AGENTS.md)
-for architecture, invariants and contribution checks.
-
-Report bugs through [GitHub Issues](https://github.com/rcsaquino/pi-memoria/issues).
-Include your pi and Node versions, steps to reproduce, and relevant errors.
-Remove personal memory content and credentials before sharing logs.
-
-## Support My Work
-
-If pi-memoria is useful to you, please consider supporting my work by
-[buying me a coffee](https://ko-fi.com/rcsaquino). 😊
+There is no build step: Pi loads `index.ts` directly. `src/database.ts`, `src/hot-memory.ts`, and `src/sessions.ts` own the storage layers; `index.ts` wires them to lifecycle events and the tool schemas. Tests use temporary directories, real SQLite FTS5, real `rg`, concurrent writers, and Pi's extension loader. See [AGENTS.md](AGENTS.md) for architecture and contribution rules.
 
-<a href="https://ko-fi.com/rcsaquino" target="_blank" rel="noopener noreferrer"><img height="72" src="https://storage.ko-fi.com/cdn/kofi2.png?v=3" alt="Buy Me a Coffee at ko-fi.com" /></a>
+## Support and contact
 
-## License
+If pi-memoria is useful to you, you can support its development on
+[Ko-fi](https://ko-fi.com/rcsaquino).
 
-[MIT](https://github.com/rcsaquino/pi-memoria/blob/main/LICENSE) © 2026 rcsaquino.
+<a href='https://ko-fi.com/rcsaquino' target='_blank'><img height='72' style='border:0px;height:72px;' src='https://storage.ko-fi.com/cdn/kofi2.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>