Syncs the private memory vault to a GitHub repository, allowing agents to submit episodes via GitHub or MCP and enabling nightly pull, curate, commit, and push workflows.
Stores and organizes shared agent memory as an Obsidian vault, with entity notes, graph links, chronicle, quests, and managed regions that can be opened and edited in Obsidian.
Integrates Ollama as a local LLM provider for the curator's sleep pipeline, using Ollama models to consolidate episodes into canonical memory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hippocampus What's the canon answer about who stole the artifact?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shared, curated memory for a party of AI agents, stored as an Obsidian vault and organized like a TTRPG campaign wiki.
Agents don't dump memory and read it back. They submit episodes (raw memories) to an inbox. Hippocampus sleeps: it consolidates episodes into canon, links entities into a graph, and keeps facts honest with lane authority, rumor/canon status, and disputes for the human to rule on. It is episodic memory turned into semantic memory, like the real hippocampus.
this repo (PUBLIC) your vault (PRIVATE GitHub repo, open in Obsidian)
────────────────── ─────────────────────────────────────────────────
code · template · fictional seeds HANDBOOK.md · quests/ · characters/ · chronicle/
published as @mehrad77/hippocampus ──► inbox/<agent>/*.md ◄── agents (GitHub or MCP)
nightly `hippo sleep`: pull → curate → commit → pushThe vault uses the tool, and the tool never knows about any vault. Your memory never enters this repo.
Related MCP server: HAM
Requires Node 24+ and git.
Create a vault (omit --seed for an empty one, or pass your own seed directory):
npx @mehrad77/hippocampus init ~/vaults/my-campaign --seed example-relocationCreate a key for secret facts:
npx @mehrad77/hippocampus -v ~/vaults/my-campaign secrets keygenPush the vault to a private GitHub repo, open it in Obsidian, and point your agents at HANDBOOK.md. Then run the curator nightly (here with LM Studio; ollama, anthropic, and xai also work):
HIPPO_LLM_PROVIDER=lmstudio HIPPO_LLM_MODEL=google/gemma-4-26b-a4b-qat npx @mehrad77/hippocampus@0.1 -v ~/vaults/my-campaign sleepThe full guide, docs/USAGE.md, covers connecting agents, scheduling, the daily review, disputes, upgrades, and vault CI.
For local agents, hippo serve --agent <id> (stdio) or hippo serve --http <port> provides:
Tool | Purpose |
| Who you are (lane, authority, quests), plus the handbook |
| Queue an episode (fast, never blocks on the LLM) |
| Search entities, with graph neighbors and pending episodes |
| Full entity note / graph walk |
| The canonical answer to a factual question, with status and disputes |
| "Previously on…": chronicle, changes, upcoming deadlines, disputes |
| Objectives, status, clocks, deadline, owner |
Every fact has a status: canon / rumor / disputed / retconned.
An agent is authoritative for entities tagged with its authority domains (party/<id>.md). There its word is canon immediately. Elsewhere it's a rumor until another agent corroborates it.
Precedence is human > lane authority > corroboration > recency. A source may correct its own earlier report.
Contradictions between peers, or against the human, open disputes/<…>.md. Set ruling: there and the next sleep makes it canon.
Secret fields are age-encrypted to secrets/<entity>/<field>.age. The note only holds secret://…, and the curator can encrypt but never decrypt.
pnpm installpnpm testpnpm typecheckPath | What |
| Schemas, markdown and managed regions, vault model, reconcile rules, search, handbook, service, secrets, migrations |
| LLM adapter (AI SDK) and the sleep pipeline |
| MCP tools and resources |
| The |
| What |
| Fictional example campaign |
Read CONTRIBUTING.md and docs/DEVELOPING.md (developing against your own private vault without leaking it). Coding agents: see AGENTS.md. Architecture: DESIGN.md.
This server cannot be deployed
Hosted self-curating shared memory that keeps your agents working like a high-performing team
Hosted agent memory: store, search, and recall facts across sessions from any MCP client.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Persistent AI memory with semantic search, conflict detection, and ticketing.
