lore

Lore

A persistent, git-synced knowledge base for dev teams — readable by humans in Obsidian and by AI assistants via MCP.

Lore gives your team a shared vault where architecture decisions, coding conventions, debugging insights, and research findings accumulate over time instead of getting lost between sessions. Notes are written as claims, reviewed like code, and promoted through a lifecycle that mirrors your git workflow.

Why

Per-developer memory tools (claude-mem, auto-memory, .claude/ files) work well for individual context, but they're invisible to the rest of the team. When a new developer joins a session — or the same developer starts a fresh one — the context rebuilding starts over. Lore solves this by making team knowledge a shared, versioned artifact that any editor can read and write through MCP.

Notes follow a git-like lifecycle: exploratory on feature branches, promoted to established on merge, or discarded on branch abandonment. Only validated knowledge reaches main.

Packages

lore/
├── vault-mcp/         TypeScript MCP server — portable vault operations
├── vault-sync/        Claude Code plugin — intelligent orchestration layer
└── vault-animation/   Remotion animations for demos

The vault template lives in its own repo: mahuebel/vault-template

vault-mcp

A TypeScript MCP server that provides 12 tools for vault operations. Works with any MCP-compatible editor — Claude Code, Cursor, Windsurf, VS Code Copilot, etc.

Tools:

Category	Tools
Config	vault-init
CRUD	vault-create-note, vault-read-note, vault-update-note, vault-delete-note
Lifecycle	vault-promote, vault-discard
Query	vault-query, vault-search
Git Sync	vault-pull, vault-push, vault-status

vault-sync

A Claude Code and Cursor plugin that adds intelligent orchestration on top of vault-mcp:

• Skills: /vault-note, /promote-to-vault, /vault-cleanup, and a setup wizard
• Observation daemon: Background service that silently captures tool use data and evaluates it for vault-worthiness using a separate AI session
• Vault context injection: Automatically searches the vault for relevant established notes and injects them into your session when you ask a question
• Agent: Promoter agent that reviews exploratory notes and recommends promote/edit/discard
• claude-mem integration: When claude-mem is installed, uses its pre-processed observations for richer evaluation (supercharged mode)

vault-animation

Remotion-based animations for project demos and documentation.

---

Quick Start

1. Create your team vault (global default)

Go to mahuebel/vault-template and click "Use this template" to create your team's vault repo. Then clone it locally:

git clone [email protected]:your-org/your-vault.git ~/obsidian/team-vault

2. Configure the MCP server

No build step required — the server runs via npx:

Claude Code:

claude mcp add --scope user \
  --env VAULT_PATH=/path/to/your/team-vault \
  --env VAULT_AUTHOR=your-github-username \
  -- vault-mcp npx lore-vault-mcp

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "vault-mcp": {
      "command": "npx",
      "args": ["lore-vault-mcp"],
      "env": {
        "VAULT_PATH": "/path/to/your/team-vault",
        "VAULT_AUTHOR": "your-github-username"
      }
    }
  }
}

Restart your editor after adding.

3. Initialize the vault connection

Call the vault-init MCP tool (or use /vault-setup if you installed the plugin):

vault-init --vault_path ~/obsidian/team-vault --author your-github-username

4. Install the vault-sync plugin (recommended)

This adds skills, hooks, and the promoter agent. See Editor Compatibility for install instructions per editor.

5. Open in Obsidian (optional)

Open your vault folder as an Obsidian vault for visual browsing, graph view, and manual editing.

---

Per-Repo Vaults

By default, Lore uses a single global vault at ~/.lore/vault/. This works well for teams working on related products that share conventions and architecture knowledge. But if you work across unrelated projects — or as a freelancer switching between clients — you may want a separate vault per repository.

When to use per-repo vaults

• Global vault (default): Best for teams on related products who benefit from shared context across repos
• Per-repo vault: Best for unrelated projects, freelancers with multiple clients, or repos with sensitive knowledge that shouldn't leak across projects

Quick start

Run the setup wizard in any project:

/vault-setup --project

This creates a .lore/config.json in your project root with your vault configuration.

Configuration format

The .lore/config.json file: