Purpose
hypermnesic is aimed at developers and heavy note-takers who want to give their own AI agents persistent memory. Its core idea is "one brain, serving all AIs": your second brain is stored in pure Markdown form in a Git repository that you host yourself, ChatGPT, Claude, and coding agents (whether on laptop or phone) all read and write this brain through the same endpoint, while Obsidian is used for browsing.
Unlike solutions that store memory in vendor-hosted storage, hypermnesic makes the files themselves the memory; the search index is merely a disposable projection that can be deleted and rebuilt at any time, and rebuilding the index never loses memory. Every memory write is a real Git commit that can be reviewed and rolled back.
Main capabilities
- Shared and compounding memory: because all AIs are maintaining the same set of notes, memory is not just persistent, it also keeps accumulating. Any AI can capture a note (a decision, fact, person, meeting), other AIs can relate, correct, or supplement context, and afterward every AI can retrieve it when answering.
- Single endpoint, multi-client access: any application that supports MCP can use it by pointing at your endpoint URL, with OAuth handled automatically. Supports ChatGPT and Claude (desktop, mobile, web) via custom connectors; Claude Code / Codex use the bundled plugin; self-built agents can use any MCP client to access the same URL; Obsidian can browse through a read-only companion over the tailnet.
- Hybrid retrieval: uses SQLite FTS5 (lexical) and sqlite-vec KNN (dense, using OpenAI text-embedding-3-large 1536 dimensions) fused via RRF; gracefully degrades to lexical-only mode when the embedding service is unavailable.
- Convergence on read: each read first catches the index up to HEAD, keeping recall fresh without manual index rebuilds.
- Git-first write path: commit_note accepts a caller-provided repository-relative path, passes through the diff-or-die front-matter gate, blocklist write guard, single-writer lock, and append-only audit log, and commits the note to git.
- Memory management: the memory command can list and inspect memorized files, export Markdown and source information, preview and apply git-based forgetting/deletion, roll back recent safe single-file writes, and view audit and denial history.
- Client management: the clients command can list OAuth authorization metadata without credentials and revoke authorization, without exposing any tokens or secrets.
- Human interface: provides thinking mode, salience plus spaced-repetition summaries, unexpected connections, an always-organized navigation interface, multi-format attachment extraction (PDF/DOCX/XLSX/PPT), and more.
How to use
The material provides a phased usage path:
- Local verification: on the machine hosting the vault, prepare a git repository of Markdown notes. Configuring OPENAI_API_KEY enables dense embeddings to improve ranking, and the offline lexical mode can also complete verification. The verification path validates a git-backed vault, projects committed Markdown files into a disposable .hypermnesic/ index, answers natural-language questions and returns repository-relative source paths, and also shows a dry-run diff of commit_note.
- Self-hosted endpoint: requires installing and logging in to Tailscale (tailscale up); hypermnesic uses Tailscale Funnel to provide public HTTPS and automatic TLS, with no reverse proxy or certificate management required. setup generates and starts a user service, generates an owner-only-readable consent secret, configures the funnel, and verifies the HTTPS discovery chain.
- Connect a client: point the application's MCP server at the endpoint URL; on first connection the application completes a one-time OAuth authorization through the browser, after which it refreshes silently. Read permission is granted by default, and write permission must be approved on the consent page.
- Local use: the host running the engine can skip the network and use the CLI directly.
- Daily loop: the material recommends a daily flow of capture -> triage -> recall -> write -> review -> clean up, and provides a daily review dashboard.
Applicable scenarios
Suitable for scenarios requiring persistent project memory: source-backed facts, decisions, processes, raw captures, generated summaries with citations, and current-state mirrors that should span the current session.
Not suitable for short-lived session stateor behavioral preferences (for example, "the user likes concise replies" should by default go in a behavioral memory layer such as Honcho), nor should secrets, credentials, private keys, tokens, or unreviewed sensitive material be written.
Limitations
- Currently a public v0.1.0 release.
- The engine is licensed under AGPL-3.0-only; the companion plugin comes from the separate GPL-3.0 hypermnesic-companion repository, with the first companion release being 0.3.0.
- By default, services with writes enabled require OAuth authentication. The advanced option --allow-tailnet-write allows tailnet membership alone as the write boundary, but only takes effect on Tailscale CGNAT addresses; non-tailnet bindings are still rejected.
- Write protection rejects .git/, .github/, agent instruction files such as CLAUDE.md / AGENTS.md, scripts/ / hooks/ / skills/, and build/CI/credential files, regardless of whether an allowlist is configured.
- Cloud access tokens are valid for 48 hours by default, with refresh for 30 days.
- Positioned differently from mem0 / Zep (managed memory services), Hindsight (self-owned vector storage), and Honcho (behavioral memory layer); hypermnesic optimizes for self-owned, auditable, compounding files rather than leaderboard rankings.
- Specific performance data, billing information, pricing, and complete installation command steps are not yet provided.
