evoctx 0.1.0__tar.gz

evoctx-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: pip install -e .[dev]
+      - name: Test
+        run: pytest tests/ -v
+      - name: Build wheel
+        run: |
+          pip install build
+          python -m build

evoctx-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC) — no API token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # to create the GitHub release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

evoctx-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+
+# Local store / personal data — never commit
+*.db
+context/
+
+# Client configs with machine-specific paths
+.mcp.json
+mcp.cmd
+
+# Design doc — private, never ship
+personal-context-layer.md
+/personal_docs/

evoctx-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+## 0.1.0 — 2026-07-14 — first beta
+
+Initial public release: a local, personal context store for AI coding assistants over MCP.
+
+**Store & tools**
+- SQLite store with FTS5 search — porter stemming (word-form matching) plus a hand-curated
+  dev-term synonym dictionary ("auth bug" also finds "login failure"); projects, notes, and
+  work sessions
+- 9 MCP tools: `list_projects`, `get_project`, `search_context`, `get_by_id`, `write_note`,
+  `start_session`, `end_session`, `recent_sessions`, `list_grants`
+- Sessions registered at start (not just summarized at the end) so an interrupted session still
+  surfaces its intent and partial notes instead of vanishing silently
+- Every note records `author_client` — which client wrote it, so past notes read as
+  informational context rather than as commands from the current session
+
+**Policy engine**
+- Grants (`grants.yaml`, hand-edited, hot-reloaded): per-client tool allow-lists, project/tag
+  scoping, mandatory expiry
+- Write-time secret redaction, unconditional, at the storage layer — common secret shapes are
+  masked before they ever touch disk, regardless of entry point or active grant
+- Read-time per-grant redaction with stable session-local tokenization
+- Append-only audit log (SQL-trigger enforced) recording every tool call, denial, and the
+  effective post-redaction query
+
+**CLI (`evoctx`)**
+- Full parity with every MCP tool, plus human-only operations an AI client can never call:
+  `delete`, `delete-project`, `export` (JSON/Markdown)
+- `evoctx install <client>` writes MCP config for Claude Code, Claude Desktop, Cursor,
+  Windsurf, VS Code, and Codex CLI
+- `evoctx install claude-code --hooks` additionally wires SessionStart/Stop hooks and
+  `permissions.deny` rules — the one enforcement mechanism beyond convention
+- `evoctx doctor` — store health, schema version, active grant, cloud-sync warning,
+  activity-staleness warning, client-config detection
+
+**Safety & portability**
+- WAL-mode SQLite for real multi-process concurrency
+- Cross-platform store location via `platformdirs`, with a legacy-path fallback for
+  pre-packaging installs
+- Schema migrations (`PRAGMA user_version`), including a guard against opening a store with a
+  newer release than the running code
+
+See [SECURITY.md](SECURITY.md) for what this does and doesn't protect against, and
+[CONTRIBUTING.md](CONTRIBUTING.md) for the schema, so your data is never locked to this
+project's code.

evoctx-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+evoctx is a young, single-maintainer project. That's a real risk if you're trusting it with
+your accumulated notes — projects like this stall. Two things are designed to make that survivable
+rather than catastrophic if it happens.
+
+## Your data outlives the project
+
+The store is 4 plain SQLite tables. If this project goes quiet, your data isn't locked in —
+it's queryable with any SQLite client on day one, and `evoctx export` (or `sqlite3 store.db`
+directly) gets it all out in JSON or Markdown.
+
+```sql
+notes(id, title, content, project, tags, session_id, author_client, created_at, updated_at)
+projects(name, overview, conventions, open_questions, updated_at)
+sessions(id, project, client, intent, started_at, ended_at, summary)
+audit_log(id, ts, connection_id, client, grant_name, tool, action, query,
+          record_ids, result_count, response_bytes, redactions_applied)
+```
+
+`tags` is a JSON array stored as text. Everything else is exactly what it looks like. No opaque
+blobs, no proprietary format, no encryption key you'd need this project's code to unwrap.
+
+## How to contribute
+
+- **Bug reports / feature requests:** open an issue. Include `evoctx doctor` output — it covers
+  version, schema version, store size, and client-config detection in one command.
+- **Pull requests:** run `pytest tests/ -v` before opening one; CI runs the same matrix
+  (ubuntu/macOS/Windows × Python 3.10/3.12). New MCP tools need a CLI mirror in the same PR —
+  see the parity table in [README.md](README.md#cli-evoctx).
+- **Security concerns:** see [SECURITY.md](SECURITY.md) first — it may already be a documented,
+  known limitation rather than something to report as new.
+
+## Design principles, if you're extending this
+
+- **CLI/MCP parity.** Every MCP tool gets a CLI mirror. The store must stay human-operable, not
+  just AI-operable.
+- **Deletion and bulk export are human-only.** Never add an MCP tool that deletes or bulk-exports.
+  This is deliberate, not an oversight to "fix."
+- **Grants gate the MCP path, not the filesystem.** Don't design a feature that implies it's a
+  sandbox against the AI client itself — see SECURITY.md §1.
+- **Write-time redaction lives in `db.py`, not `policy.py`.** It has to catch CLI writes too,
+  which never pass through the policy engine. Keep the built-in secret floor at the lowest
+  common layer.

evoctx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evo Bytes SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

evoctx-0.1.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: evoctx
+Version: 0.1.0
+Summary: Local personal context store for AI coding assistants, exposed over MCP — by Evo Bytes
+Project-URL: Homepage, https://evobytes.ro
+Author-email: Evo Bytes SRL <info@evobytes.ro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,context,mcp,memory,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<2,>=1.9
+Requires-Dist: platformdirs>=4
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# evoctx
+
+A local, personal context store for AI coding assistants, exposed over [MCP](https://modelcontextprotocol.io). By [Evo Bytes](https://evobytes.ro).
+
+Your assistant reads project context at session start, searches past decisions mid-work, and writes notes back before ending — so the next session (in any MCP-capable client) starts oriented instead of from zero. One SQLite store on your machine, shared across every workspace and every client that connects. No cloud component.
+
+> **Status: pre-beta.** Grants, redaction, audit logging, and sessions all work today. Not yet on PyPI — install from source until the first tagged release. Expect breaking changes until then.
+
+---
+
+## Install
+
+Requires Python 3.10+. Until the package is on PyPI, install from source:
+
+```
+git clone <repo-url>
+cd evoctx
+python -m venv .venv
+.venv/bin/pip install -e .          # Windows: .venv\Scripts\pip.exe install -e .
+```
+
+This installs one command into the venv: `evoctx`.
+
+- `evoctx <subcommand>` — the CLI for humans. `evoctx help` shows everything.
+- `evoctx serve` — launches the MCP server (stdio). Not for humans; your AI client runs this via its MCP config, written for you by `evoctx install` below.
+
+## Making `evoctx` a system command
+
+Right after install, `evoctx` only exists inside the venv — running it from a normal terminal
+needs the full path or an activated venv. To get a plain `evoctx` from anywhere:
+
+**Recommended: [pipx](https://pipx.pypa.io)** (installs the CLI into its own isolated
+environment and puts it on PATH for you, on Windows/macOS/Linux alike):
+
+```
+pipx install -e .                # from this repo, for now
+pipx install evoctx               # once it's on PyPI
+```
+
+**Alternative: [uv](https://docs.astral.sh/uv/)**, same idea:
+
+```
+uv tool install -e .
+```
+
+**Manual, no extra tool** — add the venv's executable folder to your `PATH`:
+
+```powershell
+# Windows (PowerShell) — persists across terminals
+[Environment]::SetEnvironmentVariable("Path", "$env:Path;$PWD\.venv\Scripts", "User")
+```
+
+```bash
+# macOS / Linux — add to ~/.zshrc or ~/.bashrc
+export PATH="$(pwd)/.venv/bin:$PATH"
+```
+
+Either way, only the CLI needs a friendly name on `PATH` — MCP client configs reference
+the `evoctx` executable by full path (`evoctx install` resolves and writes that path,
+plus the `serve` argument, for you).
+
+## Where everything lives
+
+One folder holds it all — run `evoctx doctor` and read the "store dir" line:
+
+| File | What it is |
+|---|---|
+| `store.db` | The store: notes, projects, sessions, audit log (SQLite) |
+| `grants.yaml` | What connected AI clients may do — hand-edited, hot-reloaded |
+| `active_grant.json` | Which grant is currently active (written by `evoctx grant activate`) |
+
+Default folder (first match wins):
+1. `CONTEXT_STORE` env var, if set
+2. `~/.context/` if a store already exists there (legacy)
+3. Per-OS user data dir — Windows: `%LOCALAPPDATA%\evoctx`, macOS: `~/Library/Application Support/evoctx`, Linux: `~/.local/share/evoctx`
+
+## First ten minutes
+
+```bash
+# 1. See that everything is healthy (also prints where your store lives)
+evoctx doctor
+
+# 2. Try it with sample data
+evoctx demo-seed
+evoctx search "JWT"                  # finds the demo decision note
+evoctx get-project demo-webapp      # overview, conventions, open questions
+
+# 3. Register your real project (auto-detects stack from package.json/pyproject/README)
+cd ~/code/my-api
+evoctx init
+
+# 4. Connect your AI client and restart it
+evoctx install claude-code          # or: cursor, windsurf, vscode, codex, claude-desktop
+
+# 5. Paste the instructions snippet into the client's rules file
+#    (docs/instructions-snippet.md — this is what makes the AI actually use the store)
+
+# 6. Work normally. Afterwards, see exactly what the AI did:
+evoctx audit --since 1h
+evoctx recent-sessions
+```
+
+From then on: the AI registers a session when it starts, reads your project context, records
+decisions as it works, and closes the session with a summary. Next session — same client or a
+different one — starts oriented.
+
+## Connecting a client
+
+```
+evoctx install claude-code     # or: claude-desktop, cursor, windsurf, vscode, codex
+evoctx doctor                  # verify store, grants, server command, client configs
+```
+
+`install` writes the MCP block into the client's config (existing file backed up to `.bak`,
+existing entries merged, block printed for manual paste). Manual per-client setup:
+[docs/clients.md](docs/clients.md). ChatGPT Desktop is not supported — no local stdio MCP.
+
+`doctor` checks package/store/schema/FTS5/grant/server-command/client-configs, plus:
+store size and note count, days since the last note or session (a configured client with no
+recent activity usually means the instructions snippet isn't actually being followed), and
+whether the store folder sits inside OneDrive/iCloud/Dropbox/Google Drive — those sync an
+unencrypted SQLite file off-device by default, silently.
+
+**Claude Code only:** `evoctx install claude-code --hooks` additionally writes `SessionStart`
+and `Stop` hooks into `~/.claude/settings.json` (backed up first, like every other `install_*`
+write) — the one enforcement mechanism in this project that goes beyond convention.
+`SessionStart` nudges the assistant to call `start_session`/`recent_sessions`; `Stop` blocks
+**once** (never twice — it checks Claude Code's own `stop_hook_active` flag) if a session opened
+in the last 12 hours was never closed with `end_session`. It's a nudge, not a lock: ignoring the
+message and asking Claude to stop again always succeeds.
+
+Then tell the assistant to actually use it — add to your global instructions file (e.g. `~/.claude/CLAUDE.md`; canonical version in [docs/instructions-snippet.md](docs/instructions-snippet.md)):
+
+```markdown
+## MCP Context Store (evoctx)
+MUST DO, every session:
+- **Start:** call `start_session(project, intent)` first, then `recent_sessions()` — open entries
+  were likely interrupted; check their notes. Then `get_project(name)` for anything the task touches.
+- **Before any non-trivial decision:** `search_context()` first — don't contradict a stored decision
+  without surfacing it.
+- **As you go:** `write_note()` for non-obvious decisions/gotchas immediately (auto-linked to the session).
+- **End:** call `end_session(summary)` — what was built, decided, and left open.
+```
+
+## MCP tools
+
+| Tool | When the assistant uses it |
+|---|---|
+| `start_session(project?, intent?)` | First call of a session — registers the work session; every `write_note` after is linked to it |
+| `recent_sessions(project?, limit?)` | Right after — see what recent sessions did; open ones were likely interrupted, their notes are the only record |
+| `list_projects()` | Discover registered projects |
+| `get_project(name)` | Load overview, conventions, open questions, recent notes |
+| `search_context(query, project?, limit?)` | Find relevant notes mid-work |
+| `get_by_id(id)` | Full content after a search hit |
+| `write_note(title, content, project?, tags?)` | Record decisions and observations as you go |
+| `end_session(summary)` | Last call — closes the session with what was built/decided/open |
+| `list_grants()` | What the active grant allows — so "do you have access to X?" gets an honest answer |
+
+Writes are append-only by design: the assistant can add notes but never edit or delete. Deletion is a human-only operation. Note content over 256KB is rejected — split it into multiple notes. Every note also carries `author_client` (`cli` for a human, the client name for an assistant) so past notes read as informational context, not as instructions from the current session.
+
+**Why sessions instead of just an end-of-session note:** a summary written at the end depends on the session surviving to the end. A session registered at the start shows up in `recent_sessions()` even if it crashes one minute in — flagged open, with its intent line and any notes it managed to write. Interrupted work stays visible instead of vanishing.
+
+## CLI (`evoctx`)
+
+Every MCP tool has a CLI mirror — the store is fully human-operable, not just AI-operable:
+
+| MCP tool | CLI |
+|---|---|
+| `list_projects()` | `evoctx list-projects` |
+| `get_project(name)` | `evoctx get-project NAME` |
+| `search_context(...)` | `evoctx search-context QUERY [--project NAME] [--limit N]` (alias: `search`) |
+| `get_by_id(id)` | `evoctx get-by-id ID` — ID prefix is enough (alias: `show`) |
+| `write_note(...)` | `evoctx write-note "Title" --project NAME --tags "#decision" --text "..."` (alias: `add`) |
+| `start_session(...)` | `evoctx start-session [--project NAME] [--intent "..."]` |
+| `end_session(summary)` | `evoctx end-session "summary" [--id ID]` — default: latest open |
+| `recent_sessions(...)` | `evoctx recent-sessions [--project NAME] [--limit N]` |
+
+Plus store management commands with no MCP equivalent (deliberately — deletion and bulk ops are human-only):
+
+```
+evoctx init [--dir PATH] [--template NAME]   # register project (auto-detects stack)
+evoctx new-project NAME --overview "..."
+evoctx import-dir path/to/notes/ --project NAME
+evoctx update-project NAME --field conventions --file conventions.md
+evoctx list [--project NAME]                  # list notes
+evoctx delete ID | --project NAME | --tag TAG # delete note(s) — asks to confirm, or pass --force
+evoctx delete-project NAME [--with-notes]     # delete a project (notes kept unlinked by default)
+evoctx export [--format json|markdown] [PATH] # export everything — the whole store is yours to take
+evoctx dump [--project NAME] [--note ID]      # read-only dump of the whole store
+evoctx templates                              # reusable convention templates (_fastapi, ...)
+evoctx sync [PATH]                            # sync a markdown folder into the store
+evoctx demo-seed                              # sample data to try things out (never automatic)
+```
+
+**Deletion and export exist because privacy and portability are only real if you can act on
+them.** Deletion is CLI-only, confirmed by default, never an MCP tool — an AI client can add
+to the store but never remove from it. Export dumps every project, full note content, and every
+session to JSON or Markdown, so "portable across vendors" is a command you can run, not a claim
+you have to trust.
+
+## Grants — what a client may do
+
+Every tool call passes a policy gate. Grants live in `grants.yaml` in your store folder
+(hand-edited, hot-reloaded — no restart needed); exactly one is active at a time.
+
+First run auto-creates an `everything` grant (all tools, all projects, 30-day expiry) and
+activates it, so nothing is broken out of the box. When it expires, calls fail with a message
+naming the fix:
+
+```
+evoctx grant activate everything
+```
+
+To tighten from there, add a scoped grant to `grants.yaml`
+(full commented examples: [examples/grants.example.yaml](examples/grants.example.yaml)):
+
+```yaml
+  - name: daily-coding
+    client: "*"
+    tools: [list_projects, get_project, search_context, get_by_id,
+            write_note, start_session, end_session, recent_sessions, list_grants]
+    scope:
+      projects: ["*"]
+      exclude_tags: ["#personal", "#finance"]   # these notes become invisible
+    redactions:
+      - pattern: "sk-[A-Za-z0-9]{20,}"          # mask API keys in every response
+        replace: "[API_KEY]"
+    expires: "+7d"                               # mandatory — ISO or +Nd/+Nh/+Nm
+```
+
+…then switch to it:
+
+```
+evoctx grant activate daily-coding    # picked up by a running server immediately
+evoctx grant list                     # all grants, active one starred
+evoctx grant show daily-coding
+evoctx grant deactivate               # every call denied until re-activated
+evoctx list-grants                    # what the active grant allows (MCP mirror)
+```
+
+A denied call returns an error naming the exact `evoctx grant activate` command to fix it,
+so the AI can relay it to you. Scope-blocked notes read as nonexistent (no existence leak);
+out-of-scope **writes** fail loudly instead — silent write loss is worse.
+
+## Redaction
+
+Two layers, different jobs:
+
+**Write-time (unconditional, built-in).** Every write — `write_note`, `start_session`,
+`end_session`, from the CLI or from an MCP client, regardless of which grant is active —
+is scanned for common secret shapes (API key prefixes, AWS/GitHub/Slack/Google tokens,
+PEM private key blocks, `password=`/`token=` assignments) and masked *before it touches disk*.
+This is the one place every write path funnels through, so a pasted secret doesn't sit raw in
+`store.db` waiting for a read-time rule to hide it. Best-effort — regex can't catch every secret
+shape or a value the model paraphrases — but it means the store isn't a plaintext secrets
+aggregator by default.
+
+**Read-time (per-grant, custom).** Grants can also carry their own regex redactions, applied to
+every string leaving the store on a *read* (search hits, note content, project docs, session
+summaries — and the audit log's own query field). Placeholders are stable within a session — the
+same client name always becomes the same `[CLIENT]` token, distinct values get `[CLIENT_2]`,
+`[CLIENT_3]` — so the AI can reason about entities without learning them. The original→placeholder
+map lives in memory only and dies with the process; it is never written to disk. This layer is
+one-way and doesn't touch what's stored — only what's returned.
+
+## Audit — what did the AI actually see?
+
+Every tool call is logged to an append-only `audit_log` table (SQL triggers block UPDATE/DELETE):
+timestamp, client, connection, grant, tool, read/write/denied, the effective (post-redaction)
+query, record IDs touched, result count, response size. Response *content* is never logged —
+that would duplicate the store.
+
+```
+evoctx audit                          # newest first
+evoctx audit --client cursor --since 24h
+evoctx audit --action denied          # what got blocked, and from whom
+evoctx audit --tool get_by_id -n 100
+evoctx audit-prune --older-than 90d   # reclaim space — the one deliberate exception to append-only
+```
+
+Deliberately **not** an MCP tool: the AI reading its own access record would defeat the mirror
+and leak cross-client activity between differently-scoped grants. Human-only, CLI-only.
+
+The log grows unbounded by design — pruning it any other way would mean giving some client a
+way to edit its own trail. `evoctx audit-prune` is the single human-only exception: it drops the
+append-only triggers, deletes rows older than the cutoff, and restores them immediately.
+`evoctx doctor` shows the current row count so growth is visible, not silent.
+
+## Threat model — honest limits
+
+This is policy for cooperative clients, not a sandbox. Client identity is self-reported, the
+store is unencrypted, and an AI client with its own filesystem tools can bypass grants entirely
+by reading `store.db` or editing `grants.yaml` directly — policy gates the MCP protocol path,
+not your disk. Full breakdown, including what to actually do about it (pairing with your
+client's own permission system), in **[SECURITY.md](SECURITY.md)**.
+
+## Roadmap — known gaps, not hidden ones
+
+- **Search is keyword-based (SQLite FTS5), not semantic.** It knows word *forms* (porter
+  stemming — "configuring" matches "configuration") and a hand-curated dictionary of common
+  dev-term synonyms ("auth bug" also matches a note about "login failure" — `auth`/`login`/
+  `authentication`, `bug`/`error`/`issue`/`failure`, and similar groups in
+  [synonyms.py](src/evoctx/synonyms.py)). It does not know *meaning* — a synonym pair that isn't
+  in the dictionary, or two notes that are conceptually related without sharing any recognized
+  term, won't connect. Real embedding-based semantic search is the top post-beta priority; it's
+  a real dependency (a local embedding model or a vector index) rather than a quick addition,
+  which is why the deeper version didn't make beta — the synonym dictionary is the cheap 80% of
+  the gain without the dependency weight.
+- **Encryption at rest** — not implemented; see [SECURITY.md §4](SECURITY.md).
+- **Redaction is one-way.** Grant-based read-time redaction masks values in responses but has no
+  client-side re-hydration step to reverse it — once masked, the AI only ever sees the
+  placeholder, by design for now.
+- **No defense against prompt injection via stored notes** — see [SECURITY.md §2](SECURITY.md).
+  This isn't solved by any AI memory system today, evoctx included.
+- **Single active grant at a time** — no union semantics across multiple simultaneously active
+  grants.
+
+None of these are silent limitations — if one of them matters for your use case, it's listed
+here on purpose, not something you're expected to discover by hitting it.
+
+## Layout
+
+```
+src/evoctx/
+├── server.py    MCP server entry point (FastMCP, stdio)
+├── db.py        SQLite schema, FTS5 search, migration runner
+├── grants.py    grants.yaml model, validation, expiry, hot-reload
+├── policy.py    Policy engine — every tool call passes through here
+├── redact.py    Response redaction with stable tokenization
+├── audit.py     Append-only audit log + query helpers
+├── install.py   Client config writers + doctor checks
+├── cli.py       evoctx CLI
+└── paths.py     Cross-platform store location resolution
+docs/
+├── clients.md              Per-client manual setup
+└── instructions-snippet.md Canonical rules-file block for every client
+examples/
+└── grants.example.yaml     Commented grant recipes to copy from
+SECURITY.md      What this protects against, what it doesn't, and why
+CONTRIBUTING.md  How to contribute, and why your data outlives the project either way
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — includes the exact schema, so your notes are never
+locked to this project's code even if it stalls.
+
+## License
+
+[MIT](LICENSE) © Evo Bytes SRL