{"id":50416143,"url":"https://github.com/xlreon/substrate","last_synced_at":"2026-05-31T06:01:37.324Z","repository":{"id":360112164,"uuid":"1240072931","full_name":"xlreon/substrate","owner":"xlreon","description":"Local-first knowledge bundles for AI agents. Markdown on disk, git for history, MCP for retrieval.","archived":false,"fork":false,"pushed_at":"2026-05-25T02:50:41.000Z","size":215,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T04:28:12.865Z","etag":null,"topics":["ai-agents","claude-code","cli","cursor","knowledge-base","local-first","markdown","mcp","prompt-engineering","python"],"latest_commit_sha":null,"homepage":"https://www.sidharthsatapathy.com/substrate","language":"Python","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/xlreon.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":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-15T18:32:54.000Z","updated_at":"2026-05-25T02:50:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xlreon/substrate","commit_stats":null,"previous_names":["xlreon/substrate"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/xlreon/substrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlreon%2Fsubstrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlreon%2Fsubstrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlreon%2Fsubstrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlreon%2Fsubstrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xlreon","download_url":"https://codeload.github.com/xlreon/substrate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xlreon%2Fsubstrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33720897,"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-05-31T02:00:06.040Z","response_time":95,"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":["ai-agents","claude-code","cli","cursor","knowledge-base","local-first","markdown","mcp","prompt-engineering","python"],"created_at":"2026-05-31T06:01:35.718Z","updated_at":"2026-05-31T06:01:37.317Z","avatar_url":"https://github.com/xlreon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# substrate\n\n**Lightweight, injectable knowledge bundles for AI agents.**\n\nGit-versioned · MCP-native · Lives in your filesystem as plain markdown.\n\n[![CI](https://github.com/xlreon/substrate/actions/workflows/ci.yml/badge.svg)](https://github.com/xlreon/substrate/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n\u003c/div\u003e\n\n[📝 Blog post](https://sidharthsatapathy.com/blog/substrate-knowledge-bundles-mcp-ai-agents)\n\n---\n\nSubstrate is a local-first knowledge store designed for the agent era. You write a \"bundle\" — a markdown file with YAML frontmatter — and any MCP-compatible AI tool (Claude Code, Cursor, Zed, Continue, …) can pull it into context on demand. No daemon, no database, no embeddings server. Files on disk are the source of truth; git is the history; an MCP server is the agent-facing API.\n\n```\n~/.substrate/\n└── bundles/\n    └── 2026-05-24/\n        ├── handoff-deploy-staging.md\n        └── convention-error-handling.md\n```\n\nThat's the whole thing. Open them in your editor. Diff them with git. Grep them with ripgrep. Substrate just adds an opinionated CLI and an MCP server on top.\n\n## Why substrate\n\nYou're using AI agents every day. They forget everything between sessions. The fixes on offer:\n\n- **Mem.ai / mem0 / vector DBs** — embeddings-heavy, opaque, lossy, lock-in.\n- **CLAUDE.md / cursor rules** — global, mixed with code, no provenance.\n- **Notion / Obsidian** — not designed for programmatic agent access.\n\nSubstrate sits in the gap: **portable markdown bundles** you author deliberately, **git-versioned** so changes are auditable, and **MCP-exposed** so any agent can fetch them by id, tag, date, or substring. Nothing magic — and that's the point.\n\n## Install\n\nRequires Python 3.10+.\n\n```bash\n# Standalone CLI tool (recommended)\nuv tool install substrate-kb\n\n# Or with pipx\npipx install substrate-kb\n\n# Or editable from source\ngit clone https://github.com/xlreon/substrate.git\ncd substrate \u0026\u0026 uv tool install --editable .\n```\n\nInitialize the store (one-time):\n\n```bash\nsubstrate init       # creates ~/.substrate, git-inits it\n```\n\n## 60-second tour\n\n```bash\nsubstrate add \"deploy staging landmines\"   # opens $EDITOR on a new bundle\nsubstrate list --tag handoff               # filter by tag\nsubstrate search \"asyncpg ssl\"             # substring across id/tags/body\nsubstrate get 2026-05-24-deploy-staging-landmines | pbcopy\nsubstrate ui --open                        # static HTML dashboard\n```\n\n### Adding bundles non-interactively\n\n`substrate add` opens `$EDITOR` by default. For scripted use, four other channels:\n\n```bash\nsubstrate add \"inline note\" --body \"the body text\"           # inline string\nsubstrate add \"from a file\" --from path/to/note.md           # file path\ncat note.md | substrate add \"piped in\" --from -              # stdin\nsubstrate add \"draft + tweak\" --body \"starter\" --edit        # pre-fill, then $EDITOR\n```\n\n`--body` and `--from` are mutually exclusive. Both strip leading YAML frontmatter from the source so substrate's own frontmatter is canonical.\n\nBundles are markdown files under `~/.substrate/bundles/YYYY-MM-DD/`. Every `add` and `edit` commits to git automatically.\n\n## Where your bundles live\n\nSubstrate code lives at [github.com/xlreon/substrate](https://github.com/xlreon/substrate). You install the binary — you don't fork or clone unless you want to contribute.\n\n**Your bundles live in `~/.substrate/bundles/YYYY-MM-DD/\u003cslug\u003e.md`. Your data, not ours.**\n\n`substrate init` git-inits `~/.substrate/` locally so you get versioning for free. Want to back it up?\n\n```bash\ncd ~/.substrate \u0026\u0026 git remote add origin \u003cyour-private-repo\u003e \u0026\u0026 git push -u origin main\n```\n\nWant to move the store? Set `SUBSTRATE_HOME`:\n\n```bash\nexport SUBSTRATE_HOME=/opt/team-substrate    # shared NFS mount\nexport SUBSTRATE_HOME=~/Dropbox/substrate    # synced folder\nexport SUBSTRATE_HOME=./project-substrate    # project-local\n```\n\nSubstrate honors `SUBSTRATE_HOME` everywhere — CLI, MCP server, dashboard.\n\n## For AI agents (MCP)\n\nSubstrate ships an MCP server (`substrate-mcp`) exposing the bundle store to any MCP-compatible client.\n\n**Claude Code:**\n```bash\nclaude mcp add substrate -- substrate-mcp\n```\n\n**Cursor / Zed / Continue / other MCP hosts** — add to your MCP config:\n```jsonc\n{\n  \"mcpServers\": {\n    \"substrate\": { \"command\": \"substrate-mcp\" }\n  }\n}\n```\n\n**Tools exposed:**\n| Tool | Purpose |\n|---|---|\n| `list_bundles` | Enumerate, optionally filter by tag/date |\n| `get_bundle` | Fetch a bundle by id |\n| `search_bundles` | Substring search across id, tags, body |\n| `get_by_date` | Temporal lookup (`2026-05-24` or a range) |\n| `log_use` | Record that an agent used a bundle (optional retrieval metric) |\n\nNow your agent can pull context on demand:\n\n\u003e \"What did we decide about retry semantics last week?\"\n\u003e → agent calls `search_bundles(\"retry\", since=\"2026-05-17\")` → reads top hits → answers with citations to specific bundle ids.\n\n## Bundle format\n\n```markdown\n---\nid: 2026-05-24-deploy-staging-landmines\ncreated: 2026-05-24T19:30:00+05:30\ntags: [deployment, fly, gotcha]\ncontext_refs: []\n---\n\n# What broke\n\nasyncpg refused TLS with `?ssl=disable` — needed `?sslmode=disable` instead.\n…\n```\n\nThe format is **deliberately boring**: any text editor works, the files survive substrate being uninstalled, and your `git log` is the history. No proprietary blobs, no opaque indexes.\n\n## The dashboard\n\n`substrate ui --open` generates a single self-contained HTML file with:\n\n- 4-stat overview (total / this week / today / last activity)\n- 30-day activity bar chart\n- \"Most referenced\" leaderboard (computed from your AGENTS.md / CLAUDE.md mentions + git commit count)\n- Tag filter chips\n- Day-grouped timeline with collapsible bodies\n- Modal form to draft a new bundle and copy a one-liner shell command to land it\n\nSet `SUBSTRATE_ACTIVE_FILE` to point at the markdown file where you declare your current \"active\" bundle (e.g. `~/AGENTS.md`, `~/CLAUDE.md`, anywhere) and the dashboard will highlight that one at the top:\n\n```bash\nexport SUBSTRATE_ACTIVE_FILE=~/AGENTS.md\n```\n\nIn that file, add a line containing `ACTIVE BUNDLE` and either the bundle id (what `substrate list` prints) or the path:\n\n```markdown\n## Now\n- **ACTIVE BUNDLE:** 2026-05-24-handoff-deploy-staging\n```\n\nOr path-fragment form:\n\n```markdown\n- **ACTIVE BUNDLE:** `~/.substrate/bundles/2026-05-24/handoff-deploy-staging.md`\n```\n\nMarker text is configurable via `SUBSTRATE_ACTIVE_MARKER` (e.g. `export SUBSTRATE_ACTIVE_MARKER=PINNED`).\n\n## CLI surface\n\n| Command | What it does |\n|---|---|\n| `substrate init` | Initialize `~/.substrate` as a git-backed store |\n| `substrate add \u003cname\u003e` | New bundle in today's folder. Opens `$EDITOR` by default; `--body TEXT`, `--from FILE`, or `--from -` (stdin) for scripted input |\n| `substrate list` | List bundles, optionally `--tag` / `--date` filtered |\n| `substrate search \u003cquery\u003e` | Substring search across id, tags, body |\n| `substrate get \u003cid\u003e` | Print a bundle to stdout (pipe-friendly) |\n| `substrate use \u003cid\u003e` | Copy body to clipboard + log usage |\n| `substrate log` | Show usage log (the falsifiable retrieval metric) |\n| `substrate edit \u003cid\u003e` | Open an existing bundle in `$EDITOR` |\n| `substrate history \u003cid\u003e` | `git log` for a specific bundle |\n| `substrate ui` | Generate a static HTML dashboard |\n| `substrate --version` | Print installed version and exit |\n\nFull reference: `substrate --help`. Design notes: [SPEC.md](SPEC.md).\n\n## Design principles\n\n1. **Files on disk are source-of-truth.** Every index, cache, embedding, dashboard is disposable and rebuildable from the markdown.\n2. **Git is the history.** No custom audit log, no \"version\" frontmatter field.\n3. **Boring formats.** Markdown + YAML frontmatter. No JSON-LD, no proprietary schema.\n4. **Falsifiable retrieval.** `log_use` exists so you can prove (or disprove) that the store earns its keep.\n5. **MCP-native, not MCP-only.** The CLI works offline, in a script, in a CI job; the MCP layer is an optional adapter.\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup and conventions. Bug reports and feature requests: [open an issue](https://github.com/xlreon/substrate/issues).\n\n## Support substrate\n\n- ⭐ Star on GitHub if substrate earns its keep in your workflow\n- 💬 Share use cases in [Discussions](https://github.com/xlreon/substrate/discussions)\n- 🐛 File issues, especially for cross-platform breakage\n- 📝 Write up your integration — we'll link it from the docs\n\n## License\n\n[MIT](LICENSE) © Sidharth Satapathy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxlreon%2Fsubstrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxlreon%2Fsubstrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxlreon%2Fsubstrate/lists"}