{
  "markdown": "# cognosis-silo\n_silo-template_\n\nA **silo** is a self-contained coordination center for independent agentic projects — not a single\ncodebase, but a workspace where a human operator and AI agents (Claude Code) share long-lived context:\nprojects, working theories, settled decisions, and the tooling to search all of it. This repository is\nthe template; clone or copy it to start a new silo, run `nix develop`, and everything bootstraps itself.\n\nThis README is the newcomer's orientation. [HUMAN.md](HUMAN.md) is the operator's day-to-day digest,\n[CLAUDE.md](CLAUDE.md) is the agent-facing contract, and [SILO_MECHANICS.md](SILO_MECHANICS.md) is the\nsingle source of truth for the mechanics all of them rely on (layout, lifecycle, frontmatter contract).\n\n## What this is\n\nOne silo coordinates many independent projects. Instead of scattering context across repos and chat\nlogs, a silo keeps it in one searchable vault that both you and the agents read and write. The projects\na silo coordinates are registered in [PROJECTS.md](PROJECTS.md).\n\n## Layout & tiers\n\n```\nsilo-template/\n├── knowledge-base/        # the knowledge vault — the single source of truth (markdown/OKF/Obsidian)\n│   ├── daily/             # raw capture: append-only daily session logs\n│   ├── deep-thoughts/     # raw capture: one timestamped reflection per file\n│   ├── knowledge/         # working theory: mutable articles with confidence that decays\n│   └── projects/          # asserted canon: durable per-project documentation, never decays\n├── tools/silo-kb/         # Go tooling: derived Postgres index, lifecycle engine, MCP server\n├── prompts/               # creative prompt files kept out of the operating contract (e.g. deep-thoughts persona)\n├── workspace/             # scratch area for project checkouts and working files\n├── flake.nix              # Nix dev environment: auto-bootstraps and auto-starts the silo\n├── PROJECTS.md            # registry of the projects this silo coordinates\n├── SILO_MECHANICS.md      # single source of truth for the mechanics (layout, lifecycle, frontmatter)\n├── CLAUDE.md              # the operating contract for AI agents\n└── HUMAN.md               # the operator's digest for the human\n```\n\nThe design enforces an honest split across three stances:\n\n- **Working theories** (`knowledge/`) carry a confidence score, reinforced when re-confirmed and\n  decaying when ignored.\n- **Asserted canon** (`projects/`) is settled documentation — it never decays and is never touched by\n  the lifecycle. If it's there, it's asserted, not hypothesized.\n- **Raw capture** (`daily/`, `deep-thoughts/`) is the provenance trail both tiers cite.\n\nThe markdown tree is the **single source of truth**. Postgres (pgvector + full-text, plus a link graph\nderived from wikilinks and `sources:` provenance) is a derived search index — droppable at any time\n(`pg-nuke`) and rebuilt from the working tree in one command. If\nthe database ever disagrees with the markdown, the database is wrong. This is also why the agents can't\nharm your knowledge through the database: they retrieve through a **read-only** MCP tool\n(`query_knowledge`) and never write Postgres directly, and the index is disposable — everything durable\nlives in version-controlled markdown.\n\n## The lifecycle\n\nKnowledge here has a **lifecycle**. Theories are reinforced when re-confirmed and decay when ignored;\nones that fade to zero are archived, and ones that prove stable **graduate** into project canon. Canon\nnever decays. The full mechanics (thresholds, maturity promotion, falsification) live in\n[SILO_MECHANICS.md](SILO_MECHANICS.md).\n\n## The frontmatter contract\n\nEvery note carries YAML frontmatter with a stable `id` and a `type`; working-theory notes add\nconfidence/maturity fields that canon notes must not have. A validator (a write-time hook and a git\npre-commit gate) enforces it. See [SILO_MECHANICS.md](SILO_MECHANICS.md) for the exhaustive contract\nand [HUMAN.md](HUMAN.md) for the operator summary.\n\n## Tooling & commands\n\n```sh\nnix develop        # bootstraps everything: git, vault, build, Postgres, model, index\n```\n\nThe shell banner shows live status (✓/✗) and the full command reference; reprint it any time with\n`silo-help`. The only requirement is Nix (flakes enabled) — the dev shell bundles everything else,\nincluding [Ollama](https://ollama.com) for embeddings. If you already run a native Ollama (the macOS app\nfor Metal, or a NixOS `services.ollama`), the bootstrap reuses it instead of the bundled server.\n\n**Retrieval:** every note is chunked, embedded locally (Ollama, `nomic-embed-text:v1.5`), and indexed\nfor hybrid search — three legs fused with reciprocal rank fusion: semantic similarity and keyword rank\nas the equal-weighted primary signals, plus a lower-weighted graph leg that expands one hop along\nwikilink/provenance edges to surface linked-but-weak notes. Falsified (retired-but-retained) notes are\nexcluded by default. Agents reach it through an MCP tool (`query_knowledge`); humans through\n`silo-kb query \"…\"`. Day-to-day commands are in [HUMAN.md](HUMAN.md).\n\n## Automatic session behavior\n\nIn a Claude Code session the agents work the vault on their own: a knowledge index is injected at\nsession start, frontmatter is validated on every write, agents capture durable material to the daily\nlog and write the occasional deep thought, and a session-end pass sweeps up anything missed. See\n[HUMAN.md](HUMAN.md) for the full list.\n\n## Adding a project — and starting a new silo\n\nTo add a project to an existing silo: register it in the table in [PROJECTS.md](PROJECTS.md), then add\n`knowledge-base/projects/<name>/` notes as they earn documentation.\n\nTo start a brand-new silo from this template:\n\n1. Copy or clone this repository under a new name.\n2. `nix develop` — `silo-init` scaffolds anything missing and starts the stack.\n3. Register your projects in [PROJECTS.md](PROJECTS.md) and add `knowledge-base/projects/<name>/` notes\n   as they earn documentation.\n",
  "bytes": 5971,
  "sha": "20ac928028d232ef65ddf01311e220aaa6bd55e11842b71d30f7f8bb6ea4a83e",
  "repo_slug": "enqack/cognosis-silo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_enqack_cognosis_silo_knowledge_base_inde_3f6a1ce0/readme"
}