{"id":50147675,"url":"https://github.com/nikopastore/agent-memory-site","last_synced_at":"2026-05-24T06:01:34.941Z","repository":{"id":359876234,"uuid":"1241713492","full_name":"nikopastore/agent-memory-site","owner":"nikopastore","description":"Turn Markdown/Obsidian AI-agent memory vaults into semantic HTML dashboards, search indexes, and retrieval-ready JSONL chunks.","archived":false,"fork":false,"pushed_at":"2026-05-23T23:11:20.000Z","size":393,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T23:20:11.110Z","etag":null,"topics":["agent-memory","ai-agent","claude","codex","developer-tools","jsonl","knowledge-base","llm","local-first","markdown","obsidian","privacy","rag","retrieval","semantic-html","static-site","static-site-generator","typescript"],"latest_commit_sha":null,"homepage":"https://nikopastore.github.io/agent-memory-site/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikopastore.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-05-17T18:15:36.000Z","updated_at":"2026-05-23T22:35:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nikopastore/agent-memory-site","commit_stats":null,"previous_names":["nikopastore/agent-memory-site"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nikopastore/agent-memory-site","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikopastore%2Fagent-memory-site","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikopastore%2Fagent-memory-site/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikopastore%2Fagent-memory-site/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikopastore%2Fagent-memory-site/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikopastore","download_url":"https://codeload.github.com/nikopastore/agent-memory-site/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikopastore%2Fagent-memory-site/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33423284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"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-agent","claude","codex","developer-tools","jsonl","knowledge-base","llm","local-first","markdown","obsidian","privacy","rag","retrieval","semantic-html","static-site","static-site-generator","typescript"],"created_at":"2026-05-24T06:01:34.043Z","updated_at":"2026-05-24T06:01:34.926Z","avatar_url":"https://github.com/nikopastore.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Memory Site\n\n**Compile your Markdown vault into a portable agent memory. One build, every agent: Claude, Codex, Cursor, MCP, llms.txt.**\n\n\u003e The Pandoc of agent memory — Markdown is the database, semantic HTML is the human interface, JSONL is the retrieval layer, MCP is the runtime.\n\n[![CI](https://github.com/nikopastore/agent-memory-site/actions/workflows/ci.yml/badge.svg)](https://github.com/nikopastore/agent-memory-site/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6.svg)](https://www.typescriptlang.org/)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)\n\n`agent-memory-site` is a local-first CLI that turns a directory of Markdown notes into:\n\n1. A **private, browsable dashboard** with real client-side search.\n2. **Retrieval-ready JSONL chunks** with stable IDs, content hashes, and provenance — ready for any RAG pipeline.\n3. **A live MCP server** any agent can attach to (Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, …).\n4. **All the agent-context files at once**: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `llms.txt`, `llms-full.txt`, `/.well-known/agent-card.json`, plus `sitemap.xml` + `feed.xml`.\n\nNo service to sign up for. No editor lock-in. No competing format. The vault is just Markdown.\n\n![Dashboard preview](assets/screenshot-dashboard.png)\n\n## Architecture\n\n```mermaid\nflowchart LR\n    V[Markdown vault\u003cbr/\u003eYAML frontmatter] --\u003e P[parse + tokenize\u003cbr/\u003eextractWikiLinks]\n    P --\u003e F{privacy filter\u003cbr/\u003evisibility · sensitivity}\n    F --\u003e|excluded| R[redacted-link\u003cbr/\u003eplaceholders]\n    F --\u003e|visible| C[chunkNote\u003cbr/\u003e+ content_hash]\n    C --\u003e H[/notes/*.html/]\n    C --\u003e J[chunks.jsonl]\n    C --\u003e S[search-index.json]\n    C --\u003e M[manifest.json]\n    C --\u003e L[llms.txt\u003cbr/\u003ellms-full.txt\u003cbr/\u003eAGENTS.md\u003cbr/\u003eagent-card.json\u003cbr/\u003esitemap.xml\u003cbr/\u003efeed.xml]\n    J --\u003e MCP{{agent-memory mcp\u003cbr/\u003estdio server}}\n    MCP --\u003e A1[Claude]\n    MCP --\u003e A2[Codex]\n    MCP --\u003e A3[Cursor]\n    MCP --\u003e A4[any MCP client]\n```\n\nOne parse pass. One privacy pass. One emit pass. Every agent reads the same artifacts.\n\n## The 90-second demo\n\n```bash\nnpx agent-memory-site init ./memory\nnpx agent-memory-site build --source ./memory --out ./site --mode private\nclaude mcp add agent-memory \"npx agent-memory-site mcp --site ./site\"\n```\n\nNow Claude knows everything in your notes. Same bundle works for Codex (`codex mcp add ...`), Cursor (`.cursor/mcp.json`), and any other MCP client. Local-first, privacy-aware, no service to sign up for.\n\n## Why it exists\n\nMarkdown is the best source format for humans and Git: easy to write, diff, review, and edit with AI. But every agent reads it differently. So you end up writing the same context three times — once for `AGENTS.md`, once for `CLAUDE.md`, once for `.cursorrules` — and your RAG pipeline still doesn't know about any of it.\n\n`agent-memory-site` solves the duplication. **One vault → one build → every agent reads the same thing.**\n\n## What it does (and doesn't) compete with\n\n| Tool | What it does | What it's missing for agent memory |\n|---|---|---|\n| **[Quartz](https://quartz.jzhao.xyz/)**, **[Obsidian Digital Garden](https://github.com/oleeskild/obsidian-digital-garden)** | Publish a Markdown vault as a beautiful site **for humans** | No JSONL retrieval, no MCP, no privacy modes, no agent-context fan-out |\n| **Obsidian Publish**, **[Mintlify](https://mintlify.com/)** | Hosted SaaS publishing | Closed, paid; per-vault lock-in; not agent-portable |\n| **[Letta](https://docs.letta.com/) / [MemGPT](https://github.com/cpacker/MemGPT) / [Mem0](https://mem0.ai/)** | Agent memory frameworks with their own schemas | Heavyweight runtimes; format-locked; no human-readable export |\n| **[MCPVault](https://medium.com/@ai_transfer_lab/mcpvault-...)**, **[mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)** | Live MCP server over a vault | Editor / computer must be running; not portable; can't hand off the bundle |\n| **agent-memory-site** | Compiles vault → HTML + JSONL + MCP + AGENTS.md + llms.txt | _is this thing_ |\n\nIf you want **live editing in Obsidian piped into Claude**, use MCPVault. If you want **a single bundle you can ship, share, snapshot, and feed every agent**, use this.\n\n## Use cases\n\n| Scenario | What this gives you |\n|---|---|\n| **AI agent handoff memory** | Every session ends with a handoff note in `handoffs/`. Next session, the agent reads them via MCP and picks up cleanly. |\n| **Team agent operating system** | One shared vault. Every agent (yours + your teammates') reads the same `chunks.jsonl`. No format drift. |\n| **Obsidian Publish alternative** | Publish your vault publicly without paying $10/mo, and pick up agent-context files for free. |\n| **Private team dashboard** | `--mode private` build, serve on the LAN or behind SSO. No SaaS. No telemetry. |\n| **Retrieval substrate for a custom agent** | Drop `chunks.jsonl` into LangChain / LlamaIndex / Mem0 / Letta. Each chunk carries `content_hash` so your embedding cache survives note edits to unrelated chunks. |\n| **Public sanitized project logs** | `--mode redacted` + per-note `redact:` deny-list. Push to GitHub Pages without leaking codenames. |\n| **Agent audit trail** | The HTML pages keep provenance. \"Where did the agent get that answer?\" → click through to the source note. |\n| **AI context portable across tools** | One build → AGENTS.md (Codex/Aider) + CLAUDE.md + .cursorrules + .github/copilot-instructions.md + llms.txt. Write once, every editor sees the same instructions. |\n\n## The bigger picture\n\nAI agents are starting to accumulate durable memory. Most of it is trapped in messy Markdown files, Obsidian vaults, chat exports, and hidden local folders. That memory is hard to inspect, hard to share safely, hard to audit, hard to turn into retrieval, and hard to hand off between tools.\n\n`agent-memory-site` is the **compile step** between that mess and your agents. Markdown stays the source of truth — humans and AI both write it fluently — but every agent ends up reading a clean, privacy-filtered, retrieval-ready bundle.\n\nThis repo is the first of a family. Roadmap:\n\n- `agent-memory-lint` — validate memory quality + flag stale notes + catch unmarked secrets\n- `agent-memory-sync` — sync sections across tools (Obsidian ↔ Notion ↔ Linear)\n- `agent-memory-template` — `Use this template` GitHub repo with a starter vault wired to Pages\n- `agent-memory-bench` — eval memory usefulness (retrieval precision over a question bank)\n\n## Install\n\n```bash\nnpm install -g agent-memory-site\n# or run without installing:\nnpx agent-memory-site --help\n```\n\nRequires Node 20+. Pure local — no telemetry, no network calls, no `postinstall` scripts.\n\n## Commands at a glance\n\n```text\nagent-memory init [dir]                       # scaffold a starter vault\nagent-memory new \u003ctype\u003e \u003ctitle\u003e [--source]    # scaffold a single note\nagent-memory build --source --out --mode      # compile vault → site\nagent-memory serve --out [--port] [--no-open] # local HTTP on 127.0.0.1\nagent-memory validate --source [--json] [--strict]\nagent-memory publish-check --source --out     # pre-publish gate\nagent-memory stats --source                   # counts + health\nagent-memory emit --target \u003ctarget...\u003e --source --out\nagent-memory mcp --site \u003cdir\u003e                 # run as MCP server (stdio)\n```\n\nEvery command prints a \"Next steps\" hint block. Every command works on Windows, macOS, and Linux.\n\n### `agent-memory build`\n\n```bash\nagent-memory build --source ./memory --out ./site --mode private\n```\n\nModes:\n\n- `private` — include all parsed notes (default).\n- `public` — exclude `visibility: private|team` and `sensitivity: personal|credential|financial|medical`.\n- `redacted` — include the notes but redact emails, common API-key shapes, JWTs, bearer tokens.\n\nFlags:\n\n- `--strict-redact` — also redact phones, IPv4, credit-card-shaped digits.\n- `--base-url \u003curl\u003e` — for canonical / OG / Twitter card tags.\n- `--dry-run` — plan only; don't write files.\n- `--force` — overwrite a non-empty output directory even if it lacks the `.agent-memory-output` marker.\n\n### `agent-memory mcp` — the killer feature\n\n```bash\nagent-memory mcp --site ./site\n```\n\nRuns an MCP server over stdio that exposes a compiled site as four agent-callable tools:\n\n- `search_memory(query, type?, tag?, limit?)`\n- `get_note(id)`\n- `list_recent(limit?, type?)`\n- `list_categories()`\n\nWire it into any MCP client:\n\n```bash\n# Claude Code / Claude Desktop\nclaude mcp add agent-memory \"agent-memory mcp --site /absolute/path/to/site\"\n\n# Codex CLI\ncodex mcp add agent-memory --command \"agent-memory\" --args \"mcp --site /absolute/path/to/site\"\n\n# Cursor — add to .cursor/mcp.json\n{\n  \"mcpServers\": {\n    \"agent-memory\": { \"command\": \"agent-memory\", \"args\": [\"mcp\", \"--site\", \"./site\"] }\n  }\n}\n```\n\n### `agent-memory emit` — one vault, every format\n\n```bash\nagent-memory emit --target all --source ./memory --out .\n# Writes:\n#   AGENTS.md\n#   CLAUDE.md\n#   .cursorrules\n#   .github/copilot-instructions.md\n#   .windsurfrules\n#   .aider.conf.yml\n#   llms.txt\n#   llms-full.txt\n```\n\nOr pick a subset: `--target agents.md claude.md cursorrules`.\n\n## What `build` generates\n\n```\nsite/\n├── index.html                 — dashboard with live search\n├── 404.html\n├── favicon.svg\n├── notes/\u003cslug\u003e.html          — one page per note, semantic HTML + backlinks\n├── \u003ccategory\u003e.html            — one page per category\n├── chunks.jsonl               — RAG-ready chunks with provenance\n├── search-index.json          — keyword/metadata index (always redacted)\n├── manifest.json              — note inventory (source paths omitted in public/redacted)\n├── llms.txt                   — Anthropic-spec agent index\n├── llms-full.txt              — full-text mirror\n├── AGENTS.md                  — Linux-Foundation agent-context standard\n├── sitemap.xml                — for crawlers and AI agents\n├── feed.xml                   — RSS feed of recent notes\n├── robots.txt                 — points at sitemap + llms.txt\n├── .well-known/\n│   └── agent-card.json        — agent capability descriptor\n├── assets/\n│   ├── style.css\n│   ├── search.js\n│   └── copy.js\n└── .agent-memory-output       — safety marker for safe re-builds\n```\n\nThe chunk + manifest formats are documented with JSON Schemas at [`docs/schemas/`](docs/schemas/).\n\nEach chunk looks like:\n\n```json\n{\n  \"chunk_id\": \"projects/launch-project#goal\",\n  \"doc_id\": \"projects/launch-project\",\n  \"title\": \"Launch Project\",\n  \"heading_path\": [\"Launch Project\", \"Goal\"],\n  \"type\": \"project\",\n  \"text\": \"Ship agent-memory-site 0.2 with a built-in MCP server …\",\n  \"source_path\": \"projects/launch-project.md\",\n  \"canonical_url\": \"notes/projects-launch-project.html\",\n  \"tags\": [\"project\", \"launch\"],\n  \"tokens\": 27,\n  \"content_hash\": \"fa12d8e7c1a3\",\n  \"visibility\": \"public\",\n  \"updated\": \"2026-05-22T10:14:00.000Z\"\n}\n```\n\n## Privacy model\n\nEvery note can opt into a privacy class via frontmatter:\n\n```yaml\n---\nvisibility: public | private | team\nsensitivity: none | personal | credential | financial | medical\nredact: ['Project Codename Alpha', 'staging.internal']\n---\n```\n\nThe build enforces:\n\n- Wiki-link resolution happens **after** privacy filtering. If a public note links to `[[Private Codename]]`, the link collapses to `[redacted-link]` — the title never appears.\n- The search index strips emails / secret patterns regardless of build mode.\n- The manifest does not ship source file paths in `public` or `redacted` modes.\n- Markdown link URLs are restricted to `https?:`, `mailto:`, `tel:`, `#`, and relative paths. `javascript:` is rewritten to `#blocked`.\n- Every page sets a strict `Content-Security-Policy` (no inline scripts, no `\u003cscript\u003e` from third-party origins).\n\n\u003e **Redaction is best-effort, not a guarantee.** Use `agent-memory publish-check` before pushing anything public. Use an external scanner (Gitleaks / TruffleHog) for high-stakes deploys. See [SECURITY.md](SECURITY.md) for the threat model.\n\n## Recommended vault layout\n\n```text\nmemory/\n  MEMORY.md             # top-level summary; every agent reads this first\n  projects/             # active work\n  decisions/            # decisions + reasoning\n  facts/                # things an agent should never re-derive\n  people/               # collaborators + context\n  daily/                # daily logs / standups\n  handoffs/             # session-to-session continuity\n  procedures/           # repeatable workflows\n```\n\n`agent-memory init` scaffolds this structure plus a starter set of example notes (use `--bare` for the old empty behavior).\n\n## Configuration\n\nDrop an `agent-memory.config.json` at the project root to override defaults:\n\n```json\n{\n  \"title\": \"My Agent Memory\",\n  \"source\": \"./memory\",\n  \"out\": \"./site\",\n  \"defaultMode\": \"private\",\n  \"baseUrl\": \"https://yourname.github.io/my-memory\",\n  \"description\": \"Compiled agent memory for X.\",\n  \"redact\": [\"ProjectAtlas\"]\n}\n```\n\n## How this complements Tolaria / Obsidian\n\nUse Tolaria, Obsidian, Logseq, or your editor of choice to write and maintain Markdown. Use agent-memory-site to compile a portable bundle every agent can read. It is not trying to replace your note editor — it's the build step between your vault and your agents.\n\n## Cookbook\n\nWiring recipes for every common stack — each one is ≤ 50 lines and ships into a fresh project verbatim:\n\n- [Claude Code (MCP)](docs/cookbook/claude-code.md)\n- [Cursor (MCP)](docs/cookbook/cursor.md)\n- [Codex CLI (MCP)](docs/cookbook/codex.md)\n- [LangChain](docs/cookbook/langchain.md)\n- [LlamaIndex](docs/cookbook/llamaindex.md)\n- [Mem0](docs/cookbook/mem0.md)\n- [Letta / MemGPT](docs/cookbook/letta.md)\n- [OpenAI Assistants / Memory tool](docs/cookbook/openai-memory.md)\n- [GitHub Action — build + deploy your vault on push](docs/cookbook/github-action.md)\n\n## What a note page looks like\n\n![Note page preview](assets/screenshot-note.png)\n\n## Roadmap\n\n- Local embeddings via `--embed` (in-process WASM by default; `--embed-provider ollama|openai|gemini` for power users)\n- Adapters: `--export-to mem0 | letta | codex-memories | openai-memory`\n- `agent-memory watch` — incremental rebuild + MCP hot-reload\n- Starter packs gallery: `agent-memory init --template job-hunt-agent | paper-trading-bot | research-assistant`\n- Graph view (cytoscape over `manifest.json`)\n- VS Code / Cursor extension that auto-builds on save and points the editor's agent at the bundle\n\nSee [CHANGELOG.md](CHANGELOG.md) for what landed in 0.2.\n\n## Contributing\n\nContributions welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), run `npm run ci`, open a focused PR.\n\n## Security\n\nFor vulnerability reports, see [SECURITY.md](SECURITY.md) or open a private security advisory.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikopastore%2Fagent-memory-site","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikopastore%2Fagent-memory-site","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikopastore%2Fagent-memory-site/lists"}