{
  "markdown": "# Cognito\n\n### Persistent structured memory for Claude Code.\n\nEvery conversation you have with Claude — every decision, every debugging session, every architecture debate — disappears when the session ends. Six months of daily work, gone. You start over every time.\n\nCognito fixes this. It gives Claude a **local, structured knowledge base** on disk that it reads at session start and writes to throughout the session. No vector database, no cloud, no API calls. Just markdown files that Claude compiles, maintains, and queries — and that survive across sessions forever.\n\n**It is Claude's own memory.** Claude reads it, writes it, maintains it, improves from it.\n\n```\n                  ┌─────────────────────────────────────────────────┐\n Session N        │  Wake up: read _identity + _facts + _wisdom +  │\n ─────────────>   │  _index (~700 tokens). Full project awareness.  │\n                  │                                                 │\n                  │  Work: read wing rooms on demand as topics      │\n                  │  come up. Update pages in-place with new        │\n                  │  decisions, architecture, tasks.                │\n                  │                                                 │\n                  │  Save: hooks auto-persist every 15 messages.    │\n                  │  Diary captures process observations.           │\n <─────────────   │  Nothing is lost.                               │\n Session N+1      └─────────────────────────────────────────────────┘\n```\n\n---\n\n## Lineage\n\nThis plugin synthesizes two ideas:\n\n**Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)** — the insight that RAG re-derives knowledge from scratch on every query, while a compiled wiki accumulates and compounds. Cognito applies this: raw conversation is classified, compiled into structured pages, and updated in-place. Pages reflect current truth, not append-only history. Knowledge is created at write time, not rediscovered at read time.\n\n**[MemPalace](https://github.com/MemPalace/mempalace)** — the spatial metaphor of wings, rooms, halls, and tunnels for organizing memory. Rather than a flat folder of notes, knowledge is organized by domain (wings) and topic (rooms), with cross-references (tunnels) connecting the same concept across domains. The closet/drawer pattern provides compressed summaries that point to detailed content.\n\nThe diary system — Claude's personal observation journal that consolidates into long-term behavioral wisdom — is original to this plugin.\n\n---\n\n## Install\n\n### Option A: Local development (quick start)\n\n```bash\ngit clone https://github.com/herrhelms/cognito-plugin.git\nclaude --plugin-dir ./cognito\n```\n\n### Option B: Persistent install\n\n```bash\ngit clone https://github.com/herrhelms/cognito-plugin.git ~/cognito\nclaude plugin install --path ~/cognito\n```\n\nNow every `claude` session loads the plugin automatically. Verify with `/plugins`.\n\n### Option C: From a marketplace\n\n```bash\nclaude plugin marketplace add <marketplace-url>\nclaude plugin install cognito\n```\n\n### First run\n\nJust start Claude Code in any project. The `wake` skill auto-triggers, detects there's no vault, runs the bootstrap, and asks a few setup questions. That's it — every future session starts with Claude already knowing your project.\n\n---\n\n## Architecture\n\n### The knowledge flow\n\nCognito has two parallel compilation pipelines that both feed into session startup:\n\n```\n  COMPILE PIPELINE                         DIARY PIPELINE\n  (Karpathy LLM Wiki)                     (long-term wisdom)\n\n  ┌──────────────────┐                    ┌──────────────────┐\n  │ Raw conversation │                    │ Diary observation│\n  │ decisions, code  │                    │ patterns, flags  │\n  └────────┬─────────┘                    └────────┬─────────┘\n           │ classify + route                      │ daily entry\n           ▼                                       ▼\n  ┌──────────────────┐                    ┌──────────────────┐\n  │ Wing room pages  │                    │ dailies/         │\n  │ update in-place  │                    │ diary-YYYY-MM-DD │\n  └────────┬─────────┘                    └────────┬─────────┘\n           │ if critical fact                      │ appears 2+ times\n           ▼                                       ▼\n  ┌──────────────────┐                    ┌──────────────────┐\n  │ Boot layers      │                    │ _wisdom.md       │\n  │ _facts.md        │                    │ graduated pattern│\n  └────────┬─────────┘                    └────────┬─────────┘\n           │                                       │\n           └──────────────┬────────────────────────┘\n                          ▼\n                 ┌─────────────────┐\n                 │  NEXT SESSION   │\n                 │  Wake-up: ~700t │\n                 │  Full awareness │\n                 └─────────────────┘\n                          │\n                   ┌──────┴──────┐\n                   ▼             ▼\n              Knowledge     Wisdom\n              compounds     compounds\n```\n\nThe left pipeline handles **project knowledge** — decisions, architecture, tasks. The right pipeline handles **process wisdom** — how the user works, recurring patterns, behavioral adaptation. Both load at session start. Both compound over time.\n\n### Memory layers\n\n| Layer | File | Budget | Loaded | Purpose |\n|-------|------|--------|--------|---------|\n| L0 | `_identity.md` | ~50 tok | Always | Who Claude is in this project |\n| L1 | `_facts.md` | ~200 tok | Always | Critical project facts |\n| L1.5 | `_wisdom.md` | ~150 tok | Always | Working patterns from diary |\n| L2 | `_index.md` | ~300 tok | Always | Map of all wings and rooms |\n| L3 | Wing/room pages | ~2000 tok ea. | On demand | Domain knowledge |\n| L4 | Sessions + diary | Unlimited | Rarely | Raw history |\n\n**Wake-up cost: ~700 tokens.** Claude gets full project awareness — team, stack, decisions, working patterns — without the user re-explaining anything.\n\n### Visual representation\n\n#### Core Data\n\n![Core Data](./docs/svg-diagrams/cognito_knowledge_flow_core_data.svg)\n<img src=\"./docs/svg-diagrams/cognito_knowledge_flow_core_data.svg\">\n\n#### Docs and Commmands\n![Docs and Commmands](./docs/svg-diagrams/cognito_plugin_structured_memory.svg)\n<img src=\"./docs/svg-diagrams/cognito_plugin_structured_memory.svg\">\n\n### Vault structure\n\n```\nmemory/\n├── _identity.md              # L0: project + role + owner\n├── _facts.md                 # L1: critical facts (team, stack, blockers)\n├── _wisdom.md                # L1.5: consolidated diary patterns\n├── _index.md                 # L2: table of contents for all wings\n├── _log.md                   # Append-only audit trail\n│\n├── wings/                    # One wing per domain\n│   ├── api/\n│   │   ├── _wing.md          # Wing summary (closet → points to rooms)\n│   │   ├── decisions.md      # Choices + rationale + dates\n│   │   ├── architecture.md   # System design, schemas, flows\n│   │   ├── tasks.md          # Current work + backlog\n│   │   ├── context.md        # Requirements, constraints, goals\n│   │   ├── problems.md       # Known issues + pitfalls\n│   │   └── discoveries.md    # Breakthroughs + lessons learned\n│   └── frontend/\n│       ├── _wing.md\n│       └── ...\n│\n├── entities/                 # Cross-cutting: people, tools, concepts\n│   ├── person-alice.md\n│   └── tool-postgres.md\n│\n├── dailies/                  # Claude's personal diary\n│   ├── diary-2026-04-12.md\n│   └── diary-2026-04-11.md\n│\n├── sessions/                 # Compressed daily session summaries\n│   └── 2026-04-12.md\n│\n└── _archive/                 # Archived old content (never truly deleted)\n    ├── sessions/\n    └── dailies/\n```\n\n### Spatial organization\n\n```\n  ┌─────────────────────────────────────────────────┐\n  │  WING: api-service                              │\n  │                                                 │\n  │    ┌───────────┐  ──hall──  ┌───────────┐       │\n  │    │ decisions │            │ problems  │       │\n  │    └─────┬─────┘            └───────────┘       │\n  │          │                                      │\n  │    ┌─────┴─────┐   ┌───────────┐                │\n  │    │  _wing.md │──▶│ room page │ (the drawer)   │\n  │    │  (closet) │   │ full text │                │\n  │    └───────────┘   └───────────┘                │\n  └──────────┼──────────────────────────────────────┘\n             │\n           tunnel (cross-wing link: same topic, different domain)\n             │\n  ┌──────────┼──────────────────────────────────────┐\n  │  WING: frontend                                 │\n  │          │                                      │\n  │    ┌─────┴─────┐  ──hall──  ┌───────────┐       │\n  │    │ decisions │            │ context   │       │\n  │    └───────────┘            └───────────┘       │\n  └─────────────────────────────────────────────────┘\n```\n\n**Wings** — one per major domain (a service, a person, a project).\n**Rooms** — topics within a wing (decisions, architecture, tasks, problems, discoveries, context).\n**Halls** — connections between related rooms within the same wing.\n**Tunnels** — cross-references connecting the same topic across different wings.\n**Closets** — wing summaries that point to room pages (the drawers).\n\n---\n\n## Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/cognito:wake` | Load memory context at session start (auto-triggers) |\n| `/cognito:remember <what>` | Persist a decision, fact, or observation |\n| `/cognito:recall <query>` | Search for past knowledge |\n| `/cognito:diary [entry]` | Write a process observation or consolidate wisdom |\n| `/cognito:status` | Vault overview, stats, and health |\n| `/cognito:lint` | Audit vault health, auto-fix safe issues |\n\n---\n\n## Hooks\n\nThe plugin includes two lifecycle hooks that make memory automatic:\n\n**Stop hook** — fires after every Claude response. Counts messages and triggers a save checkpoint every 15 messages (configurable via `autoSaveInterval` in settings). Claude persists any unpersisted knowledge to the relevant wing/room pages.\n\n**PreCompact hook** — fires before Claude Code compresses the context window. This is the emergency save — Claude persists everything it knows before the context shrinks. Nothing is lost to compaction.\n\n---\n\n## The diary system\n\nThe diary is the piece that makes Claude genuinely improve over time — not just remember facts, but adapt to how you work.\n\n### What goes in the diary\n\n```markdown\n# Diary: 2026-04-12\n\n## 14:30 — User interaction pattern\nUser changed auth approach for the third time. Not indecisiveness —\nexploring the solution space. Present 2-3 options with tradeoffs next time.\n→ pattern: exploratory-decision-making\n\n## 16:15 — Codebase observation\nError handling inconsistent across API routes. Third time noticing this.\n→ flag: error-handling-inconsistency\n\n## 17:00 — Self-improvement\nMy initial architecture suggestions were too complex. User always simplifies.\n→ improve: start-simpler\n```\n\n### How wisdom graduates\n\nDiary entries tagged with `→ pattern:`, `→ flag:`, or `→ improve:` accumulate daily. When a pattern appears across 2+ different days, it gets consolidated into `_wisdom.md` — a compressed file loaded every session (~150 tokens) that changes how Claude actually behaves:\n\n```markdown\n# Wisdom\nUpdated: 2026-04-12\n\n## Working patterns\n- Decision style: exploratory — present options, not commitments\n- Session rhythm: short focused bursts, one topic at a time\n- Communication: concise, minimal questions, state assumptions\n\n## Codebase patterns\n- Error handling: inconsistent — flag when touching related code\n- Webhooks: race-condition-prone — always add retry logic\n\n## Self-corrections\n- Architecture: start simpler than instinct suggests\n- Explanations: lead with \"what\", user asks \"why\" when curious\n```\n\nThis is the difference between a tool that remembers what you said and one that learns how you think.\n\n---\n\n## Storage modes\n\n| `localCognito` | Vault location | Use case |\n|-------------------|-----------------|----------|\n| `true` | `.claude/knowledge/cognito/` | Project-local, git-committable, shared with team |\n| `false` (default) | `~/.claude/knowledge/cognito/<folder>-<hash>/` | Global, per-project isolation, private |\n\nTo switch modes, set `localCognito` in the vault's `settings.json` (inside the cognito directory), or tell Claude \"use local memory\" during bootstrap. Run `cognito-bootstrap --local` to explicitly create a project-local vault.\n\nFor local mode, consider this `.gitignore` to keep personal content out of version control while sharing project knowledge:\n\n```\n# Keep structured knowledge, skip personal content\n.claude/knowledge/cognito/dailies/\n.claude/knowledge/cognito/sessions/\n.claude/knowledge/cognito/_archive/\n```\n\n---\n\n## Plugin structure\n\n```\ncognito/\n├── .claude-plugin/\n│   └── plugin.json               # Plugin manifest\n├── skills/\n│   ├── wake/SKILL.md      # Auto-load context at session start\n│   ├── remember/SKILL.md         # Persist knowledge to wings\n│   ├── recall/SKILL.md           # Search and retrieve\n│   ├── diary/SKILL.md            # Personal observations + consolidation\n│   ├── status/SKILL.md           # Vault overview\n│   └── lint/SKILL.md             # Health audit + auto-fix\n├── agents/\n│   └── memory-agent.md           # Background maintenance subagent (Haiku)\n├── hooks/\n│   └── hooks.json                # Stop + PreCompact auto-save hooks\n├── bin/\n│   ├── cognito-bootstrap       # First-run vault creation\n│   ├── cognito-ops             # Core operations (locate, search, lint, etc.)\n│   └── cognito-autosave        # Hook script with interval counter\n├── settings.json                 # Default plugin permissions\n└── README.md\n```\n\n---\n\n## Key principles\n\n1. **Compile, don't append** — pages reflect current truth, rewritten in-place. If the database changes from MySQL to Postgres, the page says `DB: Postgres (migrated from MySQL, 2026-04-12)` — not an append at the bottom.\n\n2. **~700 token wake-up** — full project awareness without re-explanation. Claude knows your team, stack, decisions, and working patterns before the first message.\n\n3. **Read on demand** — wing rooms are loaded only when the conversation touches that topic. A session about the frontend never loads the API wing's architecture room.\n\n4. **Zero dependencies** — pure markdown and bash. No Python packages, no vector database, no API calls, no internet. Works offline, works forever.\n\n5. **Wisdom compounds** — daily diary observations consolidate into behavioral patterns. Claude doesn't just remember what you decided — it learns how you think.\n\n---\n\n## Requirements\n\n- Claude Code (any recent version with plugin support)\n- Bash (included on macOS, Linux, WSL)\n- Python 3 (used only for JSON parsing in the bin scripts)\n\nNo API keys. No internet after install. Everything local.\n\n---\n\n## License\n\nMIT\n\n---\n\n## Credits\n\nInspired by [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) and the [MemPalace](https://github.com/MemPalace/mempalace) project by Milla Jovovich and Ben Sigman. The diary/wisdom pipeline and Claude Code plugin packaging are original to this project.\n",
  "bytes": 15182,
  "sha": "280e09f469cff917437ed437b85ebf7a6bf4abbfdfe6ec3dabe6d46e4e5c685b",
  "repo_slug": "herrhelms/cognito-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_herrhelms_cognito_plugin_cognito_8ea0de0c/readme"
}