{"id":"0b13f488-6bc1-4c7d-9a8d-c4b623f6e38f","slug":"knowledge-oss","kind":"skill","name":"knowledge-oss","summary":"","owner":"antigluten","repoUrl":"https://github.com/antigluten/knowledge-oss","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-05-03T16:08:36.000Z","addedAt":"2026-10-22T01:00:10.688Z","logoUrl":"https://avatars.githubusercontent.com/u/53124465?u=0721fc8ec7d981e8b7eda44a316fe66cef7b8af2&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T21:25:37.613Z","sample":false,"url":"https://conduits.dev/tools/knowledge-oss","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# knowledge-oss\n\nA flat Obsidian vault that doubles as persistent LLM memory: ingest agent\nsessions and research exports, auto-index, and query from any project.\n\n## What this is\n\nA starter kit for keeping a personal knowledge vault that an LLM agent can\nread, write, and search. The vault is plain markdown in a flat directory,\nindexed by filename prefix and Obsidian wikilinks. One Python package —\n`python3 -m vault` — handles indexing, linting, ingest, and a retrieval eval\nharness. A `memory/` directory gives the agent durable identity, preferences,\nand project state across sessions. `CLAUDE.md` / `AGENTS.md` tells the agent\nhow to use it all.\n\nNo embeddings, no database, no service. Markdown and git.\n\n## What it gives you\n\n- **One CLI** — `vault index`, `vault lint`, `vault ingest <source>`, `vault recurrence`, `vault eval`,\n  all stdlib-only (pytest is the sole dev dependency)\n- **Config, not forks** — `.vault.toml` marks the vault root and declares\n  everything else: sources, vaults, MOC budget, glossary prefixes, project buckets\n- **Source-agnostic ingest** — a source is a directory of markdown you declare;\n  manifests track what's been processed by SHA-256, so re-runs are idempotent and\n  edited files resurface. Optional adapters bridge tools that store history as\n  something else\n- **Multi-vault routing** — declare two or more vaults with keywords and every\n  ingested note lands in the right one, with an optional model tiebreak\n- **Token-cheap retrieval** — a generated `llms.txt` router + `backlinks.md`\n  let an agent find the right notes by reading ~1k tokens instead of the\n  whole vault\n- **A lint gate** — links, frontmatter schema, grounding, and file anchors,\n  exiting non-zero so CI can hold the line\n- **Memory layout** — `memory/{user,preferences,decisions,people,current,future}.md`\n  + `memory/daily/`\n- **Append-only log** — `log.md` is the changelog of vault operations\n- **Agent skills** — `.agents/skills/` (harness-neutral), symlinked into\n  `.claude/skills/` for Claude Code\n\n## Quickstart\n\n```bash\n# 1. Clone where you want your vault to live\ngit clone https://github.com/antigluten/knowledge-oss.git ~/knowledge\ncd ~/knowledge\n\n# 2. Make it yours: edit .vault.toml (name, raw-sources path, project buckets)\n\n# 3. Open it in Obsidian (optional but recommended)\n#    File → Open vault → ~/knowledge\n\n# 4. Start an agent session in the vault\nclaude          # or codex, or pi\n\n# 5. Tell it about you: edit memory/user.md, memory/preferences.md\n#    (or just chat — the agent will offer to update these as it learns)\n\n# 6. Generate the index\npython3 -m vault index\n```\n\nTo start ingesting, declare a source in `.vault.toml` — a directory of markdown\nunder `raw_sources`:\n\n```toml\n[[source]]\nname = \"notes\"\n```\n\n```bash\nmkdir -p ~/raw-sources/notes     # drop .md files in here\n\npython3 -m vault ingest notes list\npython3 -m vault ingest notes mark <file> --slugs concept--foo,tool--bar\n```\n\nThat's the triage flow: you see what hasn't been processed, write whatever notes\nit deserves, and record which slugs came from which file. For sources where one\ndocument *is* one note, `mode = \"auto\"` writes them for you:\n\n```toml\n[[source]]\nname = \"research\"\nmode = \"auto\"\n```\n\n```bash\npython3 -m vault ingest research ingest\n```\n\nIf your tool keeps history as JSONL or an export bundle rather than markdown,\nname a bundled adapter and the source gains an `export` step:\n\n```toml\n[[source]]\nname = \"sessions\"\nexporter = \"codex\"        # or \"pi\", \"claude-chat\"\n```\n\n```bash\npython3 -m vault ingest sessions export   # native format -> markdown\npython3 -m vault ingest sessions list     # then triage as usual\n```\n\nTo check the vault stays healthy:\n\n```bash\npython3 -m vault lint          # links, schema, grounding, anchors\npython3 -m vault index --check # fails if the committed index is stale\npython3 -m pytest -q           # 234 tests, no network\n```\n\n## Pointing another project at the vault\n\nThe vault is only useful if agents working *elsewhere* reach for it. Add a\nblock like this to your harness's global instructions (`~/.claude/CLAUDE.md`,\n`~/.codex/AGENTS.md`, `~/.pi/agent/AGENTS.md`):\n\n```markdown\n## Persistent knowledge vault\n\nI keep a knowledge vault at `~/knowledge/`. Before answering non-trivial\nquestions about systems, tooling, or prior decisions, check it:\n\n1. Read `~/knowledge/llms.txt` — the token-cheap router. Follow the retrieval\n   protocol printed in it verbatim; it is the authoritative copy.\n2. Open the one relevant MOC it names (the specific shard if the parent lists\n   shards), then ≤3 notes chosen by their `description`.\n3. Never read `glossary.md` or `backlinks.md` whole. Grep them:\n   `rg -i \"^\\*\\*<term>\" ~/knowledge/glossary.md`, or\n   `rg -A1 \"## \\[\\[<stem>\" ~/knowledge/backlinks.md` for what references X.\n4. A note marked `[DEPRECATED]` is superseded — read its `superseded_by` target.\n   A note marked `[STALE]` needs verifying before you rely on it.\n5. Fall back to web search / fresh reasoning only if the vault doesn't cover it.\n\nDon't write notes from outside the vault. To file something, start a session in\n`~/knowledge/` and use its `ingest-to-vault` skill — a note written without that\ncontract fails `vault lint`.\n```\n\n## How it works\n\nThe daily loop is:\n\n```\nsources → ingest → vault → query → synthesis → vault → lint → (repeat)\n```\n\n- **Ingest:** raw markdown (Perplexity exports, agent conversation logs)\n  becomes one or more cleaned notes in the vault. Manifests track what\n  has been processed, by SHA-256, so re-runs are idempotent and edited\n  sources are re-flagged.\n- **Index:** `vault index` walks the vault and regenerates per-domain\n  MOCs (Maps of Content, auto-sharded when over the token budget), the\n  alphabetical `glossary.md`, an `llms.txt` router (a ~1k-token domain map +\n  top hubs an agent reads first), and `backlinks.md` (the inverted wikilink\n  graph for entity lookup) — all from frontmatter + the `> **TL;DR:** …` line\n  in each note.\n- **Query:** the agent reads the vault from inside the directory — index\n  files, grep, and full-text search are all available.\n- **Synthesize:** when a session produces a useful cross-note answer, it gets\n  filed as `synthesis--<slug>.md` so future sessions can rediscover it.\n- **Lint:** `vault lint` sweeps for broken links, schema violations, ungrounded\n  claims, and stale file anchors, and exits non-zero on any error.\n- **Recurrence:** `vault recurrence` counts, per note, the *later* notes that link\n  back to it — lessons the vault already held that got re-derived anyway. A\n  prescriptive note with a growing count belongs in always-on config, not in a\n  file someone has to think to open.\n\n## Vault prefixes\n\nNotes are flat files; their filename prefix declares the kind of note:\n\n| Prefix             | Purpose                              | In glossary |\n|--------------------|--------------------------------------|-------------|\n| `concept--`        | atomic knowledge note                | yes         |\n| `arch-decision--`  | ADR-style decision                   | yes         |\n| `arch-pattern--`   | reusable architectural pattern       | yes         |\n| `arch-system--`    | system overview                      | yes         |\n| `bug-pattern--`    | recurring bug pattern                | yes         |\n| `tool--`           | tool documentation                   | yes         |\n| `bug-issue--`      | specific bug + fix                   | no          |\n| `dev-snippet--`    | code snippet                         | no          |\n| `dev-workflow--`   | workflow / procedure                 | no          |\n| `dev-config--`     | configuration note                   | no          |\n| `synthesis--`      | filed query / cross-note synthesis   | no          |\n| `moc--`            | Map of Content (regenerated)         | —           |\n\nThe glossary column is the `glossary_prefixes` list in `.vault.toml`.\n\n## Configuring\n\n`.vault.toml` is the single customization surface:\n\n| Key                  | What it controls                                       |\n|----------------------|--------------------------------------------------------|\n| `name`               | vault name, used in generated headers                  |\n| `raw_sources`        | where raw exports live (default `~/raw-sources`)       |\n| `moc_token_budget`   | per-shard token ceiling before a MOC splits            |\n| `glossary_prefixes`  | which note prefixes earn a glossary entry              |\n| `[[source]]`         | where notes come from — one per raw-source directory   |\n| `[[vault]]`          | where notes go — omit entirely for a single vault      |\n| `[[domain]]`         | which MOCs exist, by filename prefix or by tag         |\n| `[[project]]`        | project buckets `moc--projects` groups notes into      |\n| `[note_types]`       | prefix → type map; overrides the default taxonomy      |\n| `skip_stems`         | root `.md` files that are working docs, not notes      |\n| `curated = true`     | on a `[[domain]]`: hand-written MOC, never regenerated |\n\nIts presence also *marks the vault root* — every `vault` command walks up from\nthe current directory to find it, so the CLI works from any subdirectory and\nnever guesses which vault you meant.\n\nFor the rest — prefix taxonomy, memory layout, daily-log format — see\n`docs/customizing.md`.\n\n## Optional: more than one vault\n\nOmit `[[vault]]` and there is one vault: this directory. Declare two or more and\nevery ingested note is routed to the one whose keywords it matches best — work in\none, personal in another, reading notes in a third — with an optional model\ntiebreak for notes keywords can't place. See `docs/multi-vault.md`.\n\n## Setup guides\n\n- `docs/setup-llm-wiki-en.md` — long-form English setup walkthrough\n- `docs/setup-llm-wiki-ru.md` — Russian-language version\n- `docs/migrating-external-vault.md` — how to fold an existing vault or\n  journal into this layout\n\n## Credits\n\nBased on the author's working knowledge vault. Public release as a\nstarter kit so others can run the same pattern.\n\n## License\n\nMIT — see `LICENSE`.\n"}