{"id":50991397,"url":"https://github.com/leonardsellem/hypermnesic","last_synced_at":"2026-06-20T03:32:34.259Z","repository":{"id":364976593,"uuid":"1256380629","full_name":"leonardsellem/hypermnesic","owner":"leonardsellem","description":"Git-first memory for AI agents: Markdown files are truth, the index is disposable, writes are reviewable commits.","archived":false,"fork":false,"pushed_at":"2026-06-15T10:50:56.000Z","size":4404,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T11:49:01.390Z","etag":null,"topics":["agent-memory","ai-agents","ai-memory","chatgpt","claude","git","markdown","mcp","obsidian","openai","second-brain","self-hosted"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonardsellem.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T18:13:25.000Z","updated_at":"2026-06-15T10:51:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leonardsellem/hypermnesic","commit_stats":null,"previous_names":["leonardsellem/hypermnesic"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/leonardsellem/hypermnesic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardsellem%2Fhypermnesic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardsellem%2Fhypermnesic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardsellem%2Fhypermnesic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardsellem%2Fhypermnesic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonardsellem","download_url":"https://codeload.github.com/leonardsellem/hypermnesic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardsellem%2Fhypermnesic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34556494,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","ai-memory","chatgpt","claude","git","markdown","mcp","obsidian","openai","second-brain","self-hosted"],"created_at":"2026-06-20T03:32:31.681Z","updated_at":"2026-06-20T03:32:34.247Z","avatar_url":"https://github.com/leonardsellem.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hypermnesic\n\n[![CI](https://github.com/leonardsellem/hypermnesic/actions/workflows/ci.yml/badge.svg)](https://github.com/leonardsellem/hypermnesic/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/hypermnesic)](https://pypi.org/project/hypermnesic/)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)\n\n![An agent writes a memory through the MCP commit_note tool, git log shows the resulting real commit, and a fresh session recalls and cites it](media/engine/hero-receipt-loop.gif)\n\n**The git-native memory layer for AI agents.** A self-hosted second brain where your\nmarkdown files are the **single source of truth** and the search index is a disposable,\nrebuildable projection of the git tree. Every agent you use — ChatGPT, Claude, the Claude\nCode / Codex plugin, an Obsidian companion — shares **one OAuth-secured MCP endpoint**\n(browser-login once, then silent refresh). On the machine that holds the vault you use the\n`hypermnesic` **CLI** directly.\n\n**Who it's for:** developers and power note-takers who want durable, portable agent memory\nthey *own* — plain markdown in their own git repo, no vendor memory database, no lock-in.\n\n**Why it's different:** files-are-truth with a throwaway index (not a proprietary memory DB),\ngit-first writes (every memory is a reviewable commit), and one endpoint every client shares.\nSee [why hypermnesic](docs/why-hypermnesic.md) and the [benchmarks](#benchmarks) below.\nProduct proof is tracked separately: use the\n[remote-client smoke checklist](docs/guides/remote-client-smoke-checklist.md) and\n[first-class product readiness checklist](docs/launch/first-class-product-readiness-checklist.md)\nbefore claiming release readiness.\n\n\u003e **Status:** public v0.1.0 release. The engine is licensed under **AGPL-3.0-only**;\n\u003e the companion plugin ships from the separate GPL-3.0\n\u003e [`hypermnesic-companion`](https://github.com/leonardsellem/hypermnesic-companion)\n\u003e repository.\n\n![Terminal demo: hypermnesic local-proof shows source-grounded recall and a dry-run write diff](docs/assets/readme-local-proof.svg)\n\nThe demo source is an [asciinema cast](docs/assets/readme-local-proof.cast). It uses only a\ngenerated `/tmp/hypermnesic-demo` vault and placeholder-safe paths.\n\n**Try it in under 5 minutes:**\n\n```sh\nuv tool install hypermnesic\nhypermnesic local-proof --demo-dir /tmp/hypermnesic-demo\n```\n\nThat creates a tiny markdown git repo, projects it into the disposable index, recalls the\nrepo-relative source note, and previews the exact `commit_note` diff without writing it.\n\n**How it compares:** hosted memory layers such as Mem0, Zep, and OpenAI memory optimize for\nmanaged convenience. Hypermnesic optimizes for owned files, auditable writes, and self-hosted\nagent access:\n\n| Question | Hypermnesic | Hosted memory layers |\n| --- | --- | --- |\n| Source of truth | Markdown files in your git repo | Service-managed memory store |\n| Write model | Git-first commits and dry-run previews | API/application-managed writes |\n| Operations | Self-hosted CLI + MCP endpoint | Managed service or app feature |\n| Evidence | LongMemEval retrieval benchmark plus product smoke gates | Varies by product; compare claims by benchmark and setup scope |\n\n---\n\n## Quick start\n\n### A. Prove local memory works\n\nStart on the machine that holds the vault. You need only a **git repo** of markdown\nnotes. Dense embeddings improve ranking when `OPENAI_API_KEY` is configured, but the\nproof also works offline in lexical mode.\n\n```sh\n# 1. install the engine from PyPI\nuv tool install hypermnesic\n\n# 2. prove recall from your own markdown files, with a dry-run write preview\nhypermnesic local-proof /path/to/your/vault\n\n# or try a tiny generated demo vault first\nhypermnesic local-proof --demo-dir /tmp/hypermnesic-demo\n```\n\nThe proof path validates a git-backed vault, projects committed markdown files into the\ndisposable `.hypermnesic/` index, asks a natural-language question, returns the\nrepo-relative source markdown path, and shows a `commit_note` dry-run diff without\ncreating a write commit. The success milestone is **Local memory works**.\n\n### B. Self-host the endpoint\n\nAfter the local proof succeeds, bring the shared endpoint online for remote apps. You need\n[Tailscale](https://tailscale.com) installed and logged in (`tailscale up`); hypermnesic\nuses Tailscale Funnel for public HTTPS + automatic TLS, so there is no reverse proxy or\ncert to manage.\n\n```sh\nhypermnesic setup /path/to/your/vault \\\n  --public-url https://\u003cyour-host\u003e.ts.net/mcp\n\n# later, diagnose without changing services, secrets, funnel routes, or git\nhypermnesic doctor /path/to/your/vault \\\n  --public-url https://\u003cyour-host\u003e.ts.net/mcp\n```\n\n`setup` renders + starts a user service, generates an owner-only **consent secret**\n(`~/.config/hypermnesic-cloud/cloud.env`, chmod 600), configures the Tailscale funnel\n(the `/mcp` mount + the OAuth discovery well-knowns), then **verifies the live HTTPS\ndiscovery chain** before reporting success. Re-running it converges to the same state.\nIt prints milestone checks, your endpoint URL, and login instructions. `--resource`\ndefaults to `--public-url`; pass it only when the OAuth resource identifier differs.\n`doctor` and `status` report local index health, remote reach, OAuth discovery, auth\nchallenge, write availability, dense key source/state, vector coverage, and client-specific\nnext actions without mutating state. Read tools also expose `degraded_reason`; after an\nembedding 429 they cool down provider calls while continuing to serve lexical/graph results.\nDense key lookup is repo-scoped: process\n`OPENAI_API_KEY` wins, otherwise the target vault's gitignored `.env` is used even when the\ncommand or MCP server starts from another working directory. Live OpenAI smoke checks stay\nopt-in with `--check-dense-live`. Dense diagnostics keep credential state separate from\nprojection state: missing indexes point to initialization, and stale/absent vectors point to\n`hypermnesic converge /path/to/vault --now --json` before a full reindex.\nBy default, new OAuth clients request `read`; admins can make new approvals request both\nread and write with `--default-client-scopes read write` or\n`HYPERMNESIC_DEFAULT_CLIENT_SCOPES=read,write`.\n\n### C. Connect a client (any remote app)\n\nPoint the app's MCP server at your endpoint URL — that's it. OAuth is automatic:\n\n- **Claude / ChatGPT (cloud connectors), Claude Code plugin, Codex:** add the MCP\n  server URL `https://\u003cyour-host\u003e.ts.net/mcp`. On first connect the app discovers the\n  OAuth server, opens a browser once for you to authorize, then silently refreshes.\n  The OAuth metadata supports both confidential clients and public clients registered\n  without a client secret.\n- **Read vs. write:** read access is the default unless the endpoint admin configures\n  `--default-client-scopes read write` / `HYPERMNESIC_DEFAULT_CLIENT_SCOPES=read,write`.\n  To grant the `commit_note` **write** tool, approve **write** on the consent page (type your\n  approval token from `~/.config/hypermnesic-cloud/cloud.env`). The consent page shows exactly\n  which scopes you're granting, lets you reject or cancel, and explains how to revoke later.\n- **Client control:** after authorization, inspect or revoke known grants on the engine\n  host with `hypermnesic clients list /path/to/vault` and\n  `hypermnesic clients revoke /path/to/vault \u003cgrant-id\u003e --apply`.\n- **Claude Code / Codex plugin:** install the plugin in `plugin/` and set\n  `HYPERMNESIC_MCP_URL` to your endpoint — the bundled `.mcp.json` is discovery-only and\n  carries no host or token. See `plugin/README.md`.\n- **Obsidian companion:** read-only over your tailnet — point it at the tailnet read\n  route `http://\u003ctailnet-ip\u003e:8848/mcp` (no OAuth; tailnet membership is the boundary). It\n  ships from the public\n  [`hypermnesic-companion`](https://github.com/leonardsellem/hypermnesic-companion)\n  repository under **GPL-3.0-or-later**; the first companion release is\n  [`0.3.0`](https://github.com/leonardsellem/hypermnesic-companion/releases/tag/0.3.0).\n  See [`obsidian-plugin/README.md`](obsidian-plugin/README.md) and the license boundary below.\n\n### D. Use it locally (on the engine host)\n\nThe host that runs the engine skips the network entirely and uses the CLI:\n\n```sh\nhypermnesic local-proof /path/to/vault                           # first local value proof\nhypermnesic retrieve /path/to/vault \"what do we know about X\"   # hybrid search\nhypermnesic think    /path/to/vault \"topic\"                     # thinking-mode\nhypermnesic resolve  /path/to/vault \"Some Entity\"               # name → page path\nhypermnesic commit-note /path/to/vault notes/x.md --body \"…\"    # git-first write (dry-run preview)\nhypermnesic memory list /path/to/vault                          # inspect/control memory\nhypermnesic memory forget /path/to/vault notes/bad.md            # preview source removal\nhypermnesic clients list /path/to/vault                         # inspect OAuth client grants\n```\n\n### E. Know what belongs in Hypermnesic\n\nHypermnesic is for **durable project memory**: source-grounded facts, decisions, procedures,\nraw captures, generated summaries with citations, and current-state mirrors that should survive\nthe current session as markdown/git truth.\n\nIt is not the default home for short-lived session state or behavioural preferences. For example,\n\"user likes terse replies\" belongs in Honcho or another adjacent behavioural memory layer by\ndefault, not in Hypermnesic. Secrets, credentials, private keys, bearer tokens, and unreviewed\nsensitive material should not be written at all.\n\nBefore writing, preserve raw evidence or cite source paths. If the destination is unclear, discover\nwritable locations first (`list_folders` / `hypermnesic list-folders`); that discovery also returns\ndirect root-local `AGENTS.md` guidance, or fallback `CLAUDE.md` guidance, for the requested root\nwhen present, with local absolute paths and endpoint URLs redacted from the returned guidance.\nSee the [memory taxonomy guide](docs/guides/memory-taxonomy.md).\n\n### F. Run the daily loop\n\nFor daily work, use the loop **capture -\u003e triage -\u003e recall -\u003e write -\u003e review -\u003e clean up**.\n\n```sh\nhypermnesic capture /path/to/your/vault \"raw observation\"\nhypermnesic daily-review /path/to/your/vault\n```\n\nThe daily review is a generated, review-gated dashboard proposal that shows capture backlog,\nrecent writes, generated surfaces, recall-mode reminders, degraded/offline state, and cleanup next\nactions. See [daily workflows](docs/guides/daily-workflows.md).\n\n---\n\n## How it works\n\nA hybrid retrieval engine over a git-tracked markdown corpus, a git-first write path,\nand the surfaces built on top:\n\n- **Hybrid retrieval** — SQLite **FTS5** (lexical) fused with **sqlite-vec** KNN (dense;\n  OpenAI `text-embedding-3-large` at **1536 dims**) via RRF, degrading gracefully to\n  lexical-only when embeddings are down.\n- **Read-time convergence** — every read first catches the index up to `HEAD`, invalidates\n  doc-surface vectors for changed markdown files, and closes a bounded slice of the dense lag\n  for chunks and doc surfaces, so recall stays fresh without a manual reindex.\n- **Two serving lanes** —\n  1. a single **public OAuth MCP endpoint** at `/mcp` (Tailscale-funnel'd HTTPS; OAuth 2.1\n     with DCR + PKCE; **read tools always, the gated `commit_note` write tool by scope**),\n     used by every remote client the same way;\n  2. a **tailnet read companion** (`:8848`, auth-off) for the Obsidian companion and the\n     proactive per-prompt hook on tailnet devices.\n\n  By default a **write-enabled** serve requires OAuth (`write_enabled ⇒ auth-required`). The\n  advanced `--allow-tailnet-write` opt-in accepts **tailnet membership itself as the write\n  boundary** — permitting an auth-off, write-enabled serve, but **only** on a Tailscale CGNAT\n  address (`100.64.0.0/10`). A non-tailnet bind is still refused (it would be a public write hole),\n  and every `commit_note` guard (the blocklist write surface, protected-path refusal, diff-or-die\n  gate, audit log) still applies. Use it only when the tailnet is your trust boundary and the\n  public OAuth lane carries all untrusted traffic.\n- **Write path** — `commit_note` takes a caller-supplied repo-relative path and commits it\n  to git through a diff-or-die frontmatter gate and a **blocklist write guard**\n  (write-anywhere-under-guards: a note may land anywhere in the vault *except* the protected\n  classes — `.git/`, `.github/`, agent-instruction files like `CLAUDE.md`/`AGENTS.md`,\n  `scripts/`/`hooks/`/`skills/`, and build/CI/credential files — which are refused regardless of\n  any allowlist), single-writer locks, and an append-only audit log. An explicit allowlist is an\n  opt-in way to *narrow* the surface, not the default guard. The index follows as a projection — a\n  reindex never loses a write. Write requires auth (`write_enabled ⇒ auth-required`).\n- **Memory control** — `hypermnesic memory` lists and inspects remembered files, exports\n  markdown plus provenance, previews and applies git-backed forget/delete, reverts safe\n  recent single-file writes, shows audit/refusal history, and answers what an agent may\n  write using the same guard as `commit_note`.\n- **Client control** — `hypermnesic clients` lists secret-free OAuth grant metadata and\n  revokes grants without exposing bearer tokens, refresh tokens, approval credentials, or\n  client secrets. The public cloud lane separately stores restart-survivable OAuth runtime\n  state in owner-only `.hypermnesic/cloud-oauth-state.json`.\n- **Security** — operator-consent gates the `write` scope at login; audience-bound tokens\n  (RFC 8707); refresh rotation + whole-grant revoke; a per-request consent CSP. See\n  `docs/2026-06-03-unified-write-anywhere-security-review.md`.\n- **Human surfaces** — thinking-mode, salience + spaced-review digest, serendipity\n  connections, an always-organized navigation surface, frictionless capture→triage,\n  multi-format sidecar extraction (PDF/DOCX/XLSX/PPTX/PNG), and a read-only Obsidian companion.\n\n## Benchmarks\n\n![LongMemEval V1 accuracy on the comparable gpt-4o-2024-08-06 judge axis: no-memory 60.2, Zep 71.2, Mastra 84.2, hypermnesic 83.2 with a GPT-4o reader and 88.6 with a GPT-4.1 reader; the GPT-4.1-judged rows OMEGA 95.4 and Mastra 94.9 are shown separately as not directly comparable](media/engine/benchmark-longmemeval.svg)\n\nOn **LongMemEval V1** (the `_s` 500-question set), hypermnesic's end-to-end QA accuracy is\n**88.6% overall / 90.2% task-averaged** with a GPT-4.1 reader, and **83.6 / 87.1** with a\nGPT-4o reader — both graded by the canonical `gpt-4o-2024-08-06` judge. Session-level retrieval\n`recall@10` is **0.949** (every gold session in the top-10 for 94.9% of questions).\n\n**Read these honestly.** They are on the matched **GPT-4o-judge** axis — the only\napples-to-apples memory-system comparison — where hypermnesic sits **on par with Mastra\nObservational Memory (84.2)**, **+12 over Zep (71.2)**, and **+23 over the no-memory\nfull-context floor (60.2)**. They are **not** comparable to the GPT-4.1-*judged* ~95%\nleaderboard rows — that gap is judge leniency, not memory quality. The full methodology,\ncomparability envelope, per-ability tables, corrections log, and a re-runnable harness\n(pinned dataset hash; `bench` extra required for the paid reader path) are in\n[`harness/BENCHMARKS.md`](harness/BENCHMARKS.md).\n\nLongMemEval measures retrieval quality. It does not prove setup, consent, memory control, or remote-client operability. Product operability is gated by the local product smoke\n(`scripts/product_smoke.py`), offline remote-contract tests, the\n[remote-client smoke checklist](docs/guides/remote-client-smoke-checklist.md), and the\n[first-class product readiness checklist](docs/launch/first-class-product-readiness-checklist.md).\n\n## Docs\n\nStart with the [documentation index](docs/README.md). Highlights:\n\n- [`ARCHITECTURE.md`](ARCHITECTURE.md) — how it works (the disposable-index invariant, retrieval, write path, serving lanes).\n- [`docs/guides/getting-started.md`](docs/guides/getting-started.md) — local proof, setup diagnosis, and failure modes.\n- [`docs/guides/memory-control.md`](docs/guides/memory-control.md) — inspect, export, forget/delete, revert, audit, and write-scope controls.\n- [`docs/guides/consent-and-clients.md`](docs/guides/consent-and-clients.md) — consent scopes, reject/cancel, client grants, and revocation.\n- [`docs/guides/remote-client-smoke-checklist.md`](docs/guides/remote-client-smoke-checklist.md) — real-client OAuth/read/write/revoke smoke evidence.\n- [`docs/launch/first-class-product-readiness-checklist.md`](docs/launch/first-class-product-readiness-checklist.md) — first-class product readiness checklist.\n- [`docs/reference/`](docs/reference/) — the MCP tool, CLI, and configuration references.\n- [`docs/unified-oauth-mcp-deploy-runbook.md`](docs/unified-oauth-mcp-deploy-runbook.md) — the unified endpoint: topology, cutover, reverse.\n- [`plugin/README.md`](plugin/README.md) — the Claude Code / Codex plugin (OAuth-discovery, distribution-generic).\n- [`docs/plans/`](docs/plans/) — the per-phase execution plans (the authoritative scope of record).\n- [`docs/threat-model-commit-note.md`](docs/threat-model-commit-note.md) + [`docs/2026-06-03-unified-write-anywhere-security-review.md`](docs/2026-06-03-unified-write-anywhere-security-review.md)\n  — the write-path threat model and the public write-surface review.\n- [`implementation-notes.md`](implementation-notes.md) — running log of decisions and deviations.\n\n## Community\n\n- [Welcome discussion](https://github.com/leonardsellem/hypermnesic/discussions/73) — project overview, support boundaries, and contribution entry points.\n- [Public roadmap](https://github.com/leonardsellem/hypermnesic/discussions/74) — near-term launch work, contribution funnel, and current non-goals.\n\n## Develop\n\n```sh\nuv sync --extra dev\nuv run pytest\nuv run ruff check .\nuv run python scripts/license_scan.py   # zero AGPL/GPL/SSPL *dependency* gate\n```\n\n## Credentials\n\nThe OpenAI key is read from `OPENAI_API_KEY` (env var or a gitignored repo-root `.env`). It is\nnever written to the index, the audit log, or any output. The OAuth consent secret lives only in\nan owner-only env file. Public-lane OAuth client/token runtime state is stored in owner-only\n`.hypermnesic/cloud-oauth-state.json` so clients can refresh across service restarts; it is never\nlogged or committed.\n\n## License\n\nHypermnesic is licensed under **AGPL-3.0-only**. See [LICENSE](LICENSE).\n\nThe `scripts/license_scan.py` \"zero AGPL/GPL/SSPL\" gate is **dependency-scoped**: it governs\nhypermnesic's *third-party dependencies*, keeping the dependency tree copyleft-free. It does **not**\ngovern — and is not contradicted by — the engine's own AGPL license: the gate excludes the\nproject's own distribution before classifying, so it stays green when the engine itself is licensed\nAGPL-3.0. Third-party dependencies are permissive and verified copyleft-free on every CI run.\n\n**Engine ↔ companion license boundary.** The Obsidian companion ships from a separate repository\nunder **GPL-3.0**; the engine is licensed under **AGPL-3.0-only**. Neither is a derivative of the\nother, and that holds **because** they are separate processes that communicate only at arm's\nlength over the MCP network protocol (`search` / `build_context` / `think`), with no shared or\nstatically-linked code. The boundary stays true only while the **companion does not vendor,\nimport, or statically link engine source** (the read-only-over-the-wire invariant). Keep that\ncondition and the two licenses remain independent.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardsellem%2Fhypermnesic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardsellem%2Fhypermnesic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardsellem%2Fhypermnesic/lists"}