{"slug": "the-institutional-memory-for-your-codebase", "title": "The institutional memory for your codebase", "summary": "Lore, a decision memory layer for projects built with Claude Code, captures the reasoning behind code changes automatically and locally alongside a project's git workflow. The tool records agent activity and decisions during sessions, distills them into structured records upon commits, and promotes relevant reasoning to permanent storage when features merge into the main branch, ensuring institutional knowledge persists without manual documentation.", "body_md": "The institutional memory for your codebase. Persistent reasoning for Claude Code — so every session knows what every previous session decided, and why.\n\n```\ngit log    # shows what changed\nlore log   # shows the lore (why it changed)\n```\n\nLore is a **decision memory layer** for projects built with **Claude Code**. It sits alongside your project like `.git`\n\n— silent, automatic, and local.\n\nWhile version control tracks the evolution of your code, Lore captures the **\"Lore\" of your project**: the reasoning, rejected alternatives, and critical constraints that normally disappear when a Claude session ends. It integrates directly with Claude Code's hook system to ensure your project's institutional knowledge grows as fast as your code.\n\nNo documentation required. No human discipline required. No changes to how agents or developers work.\n\nLore operates silently in the background, synchronizing with your git workflow to capture reasoning exactly when it happens.\n\n**Observe**— The`lore-daemon`\n\ncaptures agent activity and reasoning as it happens. Every tool use, every thought process, and every file touch is recorded.**Distill**— When you commit code, Lore automatically analyzes the changes. It identifies which sessions contributed to the surviving code and distills the raw reasoning into structured decision records.**Promote**— As features merge into your main branch, their corresponding decisions are promoted to permanent storage. Reasoning for abandoned work is automatically filtered out.\n\nThis three-tier approach ensures your knowledge base only contains the \"truth\" of your production codebase, free from the noise of discarded iterations.\n\nLore links decisions to function and class symbols, not to line numbers. Line numbers change with every refactor; symbols are stable. This ensures that the reasoning behind `checkInternalIP()`\n\nfollows the code even after it's moved or refactored.\n\n```\ncurl -fsSL https://raw.githubusercontent.com/amarlearning/lore/main/install.sh | bash\n```\n\nDone. Everything automatic from that point.\n\nTo uninstall Lore:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/amarlearning/lore/main/uninstall.sh | bash\n```\n\nOr manually remove the binaries:\n\n```\nrm $HOME/.local/bin/lore\nrm $HOME/.local/bin/lore-daemon\n```\n\n**Note:** Uninstalling does not remove `.lore`\n\ndirectories from your projects. To remove Lore data from a project, delete the `.lore`\n\ndirectory manually.\n\n**Start the daemon**: Run`lore start`\n\nto begin capturing reasoning.**Initialize your project**: Run`lore init`\n\nin your project root.**That's it!** Everything is set up automatically:- Creates the\n`.lore/`\n\ndirectory structure (temp/, staging/, decisions/) - Installs Git Hooks (\n`post-commit`\n\nand`post-merge`\n\n) to automate distillation and promotion - Registers Claude Code Hooks in\n`.claude/settings.json`\n\nto capture lifecycle events\n\n- Creates the\n\nYou don't need to do any manual configuration — `lore init`\n\ntakes care of everything!\n\nLore mirrors the tools you already know.\n\n`lore start`\n\n— Start the reasoning capture daemon.`lore stop`\n\n— Stop the reasoning capture daemon.`lore status`\n\n— Inspect your reasoning memory tiers.`lore log`\n\n— View decision history by commit hash.`lore show`\n\n— Drill into a specific decision.`lore query`\n\n— Semantic search across your entire institutional memory.\n\n**1. Why do I need Lore?**\nAI agents like Claude Code make critical decisions every session, but that reasoning disappears when the session ends. Lore captures the \"why\" behind your code, preventing \"institutional amnesia\" as your project grows.\n\n**2. Do I need to write documentation manually?**\nNo. Lore is entirely automatic. It observes what Claude is already thinking and doing, then distills that into structured records without any extra effort from you.\n\n**3. Does it change how I use Claude Code?**\nNot at all. You continue working exactly as you do today. Lore sits silently in the background, integrated via hooks, and only speaks up when it has relevant historical context to share.\n\n**4. How does Lore capture my thoughts?**\nLore uses a background daemon that listens to Claude Code's lifecycle events. It records every tool use, file touch, and reasoning block in a temporary \"working memory\" while you work.\n\n**5. When does a \"thought\" become a \"permanent record\"?**\nLore mirrors the git lifecycle. Raw thoughts stay in `temp/`\n\nuntil you `git commit`\n\n(Distillation). Those records stay in `staging/`\n\nuntil you `git merge`\n\nto your main branch (Promotion).\n\n**6. How does Claude actually use this data?**\nLore uses \"just-in-time\" memory injection. When Claude is about to touch a file, Lore intercepts the request, looks up relevant historical decisions, and injects them as context before the agent acts.\n\n**7. Does Lore inject context during research or only when editing?**\nLore is proactive. It injects reasoning as soon as Claude **reads** a file. This ensures the agent is aware of critical constraints during the planning phase, before any code is written.\n\n**8. Does this work with remote teams and PRs?**\nYes. Since Lore's data is version-controlled in the `.lore`\n\ndirectory, it travels with your repo. When you pull a teammate's merged branch, Lore automatically promotes their reasoning into your local memory.\n\n**9. What happens if I squash or rebase my commits?**\nLore handles history rewrites naturally. If you squash multiple commits, Lore automatically re-distills the reasoning from all affected sessions into a single, high-fidelity record for the final commit hash.\n\n**10. Where is my data stored?**\nLore is local-first. All reasoning and decision records are stored inside your repository in the `.lore`\n\ndirectory. Your institutional memory stays exactly where your code lives—under your control.\n\nLore is built as three independent packages that work together:\n\n``` php\ngraph TB\n    User[User] -->|lore commands| CLI[lore-cli]\n    CLI -->|uses| Core[lore-core]\n    CLI -->|starts/stops| Daemon[lore-daemon]\n    Daemon -->|captures events| Claude[Claude Code]\n    Claude -->|reads decisions| Daemon\n    Daemon -->|stores raw data| Temp[(temp/)]\n    CLI -->|distills| Staging[(staging/)]\n    CLI -->|promotes| Decisions[(decisions/)]\n    \n    style Core fill:#e1f5ff\n    style CLI fill:#fff4e1\n    style Daemon fill:#f4e1ff\n    style Temp fill:#ffcccc\n    style Staging fill:#ffffcc\n    style Decisions fill:#ccffcc\n```\n\nThe heart of Lore — contains all shared logic:\n\n**Models**: Pydantic data models for`SessionData`\n\n,`DecisionRecord`\n\n, etc.**Store**: Utilities for finding/writing to`.lore/`\n\n, loading sessions, finding decisions**Distill**: Logic for extracting symbols from diffs and distilling reasoning** Constraints**: Loading architectural constraints from AGENTS.md\n\nUser-facing command-line interface:\n\n- All user commands:\n`init`\n\n,`start`\n\n,`stop`\n\n,`commit`\n\n,`merge`\n\n,`status`\n\n,`log`\n\n,`show`\n\n,`query`\n\n,`constraints`\n\n- Git hook installation\n- Claude Code hook registration\n\nBackground HTTP server (port 7340):\n\n- Receives Claude Code lifecycle events via webhooks\n- Writes raw session data to\n`temp/`\n\n- Injects relevant decisions as context before tool use\n- Handles 5 hook types:\n`UserPromptSubmit`\n\n,`PostToolUse`\n\n,`PreCompact`\n\n,`Stop`\n\n,`PreToolUse`\n\nLore uses a three-tier storage system to ensure only high-quality, production-relevant reasoning becomes permanent knowledge:\n\n```\nsequenceDiagram\n    participant Claude as Claude Code\n    participant Daemon as lore-daemon\n    participant Temp as temp/\n    participant CLI as lore-cli\n    participant Staging as staging/\n    participant Decisions as decisions/\n\n    Claude->>Daemon: Session events\n    Daemon->>Temp: Write raw data\n    \n    Note over CLI,Temp: git commit\n    CLI->>Temp: Read raw sessions\n    CLI->>CLI: Distill reasoning\n    CLI->>Staging: Write decision records\n    \n    Note over CLI,Staging: git merge to main\n    CLI->>Staging: Read staged decisions\n    CLI->>Decisions: Promote to permanent store\n    \n    Claude->>Daemon: About to touch file\n    Daemon->>Decisions: Look up relevant decisions\n    Daemon->>Claude: Inject context\n```\n\n-\n(Raw Working Memory)`temp/`\n\n- Stores raw Claude Code session data as it happens\n- Cleared automatically after each commit\n- Never treat as truth — contains discarded experiments and dead ends\n\n-\n(Distilled Records)`staging/<branch>/`\n\n- Structured decision records distilled from\n`temp/`\n\n- Contains only reasoning about code that survived the commit\n- Cleared after merge to main\n- Never query as final — still branch-specific\n\n- Structured decision records distilled from\n-\n(Permanent Knowledge)`decisions/`\n\n- Production-grade decision records\n- Only grows when branches merge to main\n- Ghost reasoning filter ensures only decisions about surviving code are here\n- This is your institutional memory — safe to rely on\n\nDecision records are stored as YAML for token efficiency and Claude-friendliness:\n\n```\ncommit_hash: a3f9c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0\nsummary: Skip 2FA for internal IPs\nwhy: Skipped 2FA for internal IPs due to SSO compliance requirement confirmed by legal\nalternatives_rejected:\n  - Enforce 2FA for all → broke internal deploy tooling\n  - IP allowlist at firewall level → too ops-heavy\nconstraints:\n  - Must not break internal deploy pipeline\n  - Compliance review required before this block is removed\nsymbols:\n  - checkInternalIP\nfiles:\n  - auth/middleware.js\n```\n\nEach session directory contains:\n\n`prompt.json`\n\n- Initial user prompt`tool_events.jsonl`\n\n- Stream of tool use events`compact.json`\n\n- Full session state before context compaction`stop.json`\n\n- Session termination timestamp\n\nLore integrates with Claude Code via 5 lifecycle hooks registered in `.claude/settings.json`\n\n:\n\n| Hook | Purpose | When It Fires |\n|---|---|---|\n`UserPromptSubmit` |\nCapture initial task intent | At session start |\n`PostToolUse` |\nRecord every file touch and tool call | After every tool use |\n`PreCompact` |\nCapture full reasoning before context loss | Before Claude compacts its context |\n`Stop` |\nSeal the session | When session ends |\n`PreToolUse` |\nInject relevant decisions | Before Claude reads/writes a file |\n\n**Proactive Context Injection**: Lore injects decisions as soon as Claude **reads** a file, not just when it edits. This ensures the agent knows critical constraints during planning.\n\n| Component | Technology | Rationale |\n|---|---|---|\n| Language | Python 3.11+ | Excellent ecosystem for CLI tools and ML/LLM integration |\n| CLI Framework | Typer | Modern, type-safe, beautiful CLI output |\n| Web Server | FastAPI + Uvicorn | High-performance async server with automatic OpenAPI docs |\n| Data Validation | Pydantic 2.0 | Type-safe data models with excellent error messages |\n| Git Integration | GitPython | Robust git operations without shelling out |\n| Storage Format | YAML | 2-3x more token-efficient than Markdown for Claude |\n| Testing | pytest + pytest-cov | Industry-standard testing with coverage reporting |\n| Linting/Formatting | ruff | Blazing-fast linter and formatter in one |\n| Type Checking | mypy | Static type checking for robustness |\n\n```\n# Clone the repo\ngit clone https://github.com/amarlearning/lore.git\ncd lore\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install in development mode\npip install -e \"./lore-core[dev]\"\npip install -e \"./lore-daemon[dev]\"\npip install -e \"./lore-cli[dev]\"\n# Run all tests with coverage\nexport PYTHONPATH=$PYTHONPATH:$(pwd)/lore-core/src:$(pwd)/lore-cli:$(pwd)/lore-daemon/src\npytest --cov=lore_core --cov=lore_cli --cov=lore_daemon\n\n# Run pre-commit checks (same as CI)\n./hooks/pre-commit\n```\n\nAll contributions must follow:\n\n**Clean Code**: Readability, meaningful names, small single-purpose functions** TDD**: Write tests*before*implementation. Aim for >80% coverage.**Functional Programming**: Prefer immutability, pure functions, Pydantic models** Pragmatic Programming**: Build what's necessary, avoid over-engineering\n\nLore is designed with privacy as a first-class concern:\n\n**100% Local**: All data stays on your machine in`.lore/`\n\n**No Phone Home**: No data is sent to any external servers** Your Code, Your Lore**: Decision records live in your repo, under your control** No Secrets Stored**: Lore doesn't access or store API keys, credentials, or secrets** Git-Compatible**:`.lore/`\n\ncan be committed to git to share institutional memory with your team\n\n```\ncommit_hash: a3f9c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0\nsummary: Skip 2FA for internal IPs\nwhy: Skipped 2FA for internal IPs due to SSO compliance requirement confirmed by legal in ticket #234.\nalternatives_rejected:\n  - Enforce 2FA for all → broke internal deploy tooling\n  - IP allowlist at firewall level → too ops-heavy\nconstraints:\n  - Must not break internal deploy pipeline\n  - Compliance review required before this block is removed\nsymbols:\n  - checkInternalIP\nfiles:\n  - auth/middleware.js\n```\n\n", "url": "https://wpnews.pro/news/the-institutional-memory-for-your-codebase", "canonical_source": "https://github.com/amarlearning/lore", "published_at": "2026-05-26 07:37:37+00:00", "updated_at": "2026-05-26 08:12:17.517609+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-products", "mlops", "ai-infrastructure"], "entities": ["Claude Code", "Lore"], "alternates": {"html": "https://wpnews.pro/news/the-institutional-memory-for-your-codebase", "markdown": "https://wpnews.pro/news/the-institutional-memory-for-your-codebase.md", "text": "https://wpnews.pro/news/the-institutional-memory-for-your-codebase.txt", "jsonld": "https://wpnews.pro/news/the-institutional-memory-for-your-codebase.jsonld"}}