🧠 Clawdiney

Expanded Brain for Coding Agents

A hybrid Vector + Graph system that transforms your Obsidian vaults into a living knowledge source for AI coding agents.

🚀 Overview

Clawdiney is a multi-vault knowledge system. It indexes multiple Obsidian vaults — one per project — and provides semantic search + knowledge graph navigation for AI agents.

Core capabilities:

• Zero-infrastructure storage (v0.2.0): Everything lives in a single local SQLite file (brain.db) — vectors via sqlite-vec, full-text via FTS5, knowledge graph via relational tables. No Docker, no Neo4j, no ChromaDB, no Redis.
• Hybrid Search: BM25 (exact terms, acronyms, identifiers) + semantic vectors, fused with Reciprocal Rank Fusion; optional cross-encoder reranking (pip install clawdiney[rerank])
• Multi-Vault Architecture: Each project gets its own vault with isolated data (vault-scoped rows in the same database)
• CWD Auto-Detection: The system detects which vault to use based on your current working directory — no manual switching
• Knowledge Graph: Maps relationships between notes via [[WikiLinks]] and shared tags
• Linking & Fallback: Vaults can link to related vaults (e.g., SDK projects link to their parent project). Searches cascade through the chain: current vault → linked vaults → general
• Native Integration: Connects to MCP-compatible agents (OpenCode, Claude Code, etc.) via SSE or stdio
• Agent-Written Memory: write_memory turns conversational facts into provenance-marked, searchable notes — resolved against existing entities, deduped, and optionally namespaced per agent (agent_id)
• Bi-Temporal Facts & Conflict Detection: Graph facts carry validity windows; when an LLM-extracted fact genuinely changes value, both versions are kept and flagged rather than one silently overwriting the other
• Measured, Not Assumed: clawdiney-eval scores retrieval quality (recall@k/MRR/hit-rate) per mode against a regression baseline — see BENCHMARKS.md

Migrating from v0.1.x (Docker stack)? The Neo4j/ChromaDB/Redis containers are no longer used. Just install v0.2.0, keep Ollama running, and run clawdiney-index once to rebuild the index into brain.db. Your vault files are the source of truth — nothing is lost. Old Docker volumes can be removed with docker compose -f docker/docker-compose.yml down -v.

⚖️ Why Embedded SQLite Instead of a Service Stack

Peers in the AI-agent-memory space (mem0, Zep/Graphiti, Letta/MemGPT) typically run a vector DB + graph DB + cache as separate services. Clawdiney holds vectors (sqlite-vec), full-text (FTS5), and the knowledge graph in one brain.db file:

This is a deliberate trade-off: embedded SQLite means single-writer-at-a-time semantics and no built-in horizontal scaling — right for a single-user or small-team coding-agent memory layer, not a multi-tenant SaaS backend. See BENCHMARKS.md for retrieval-quality numbers (recall@k/MRR/hit-rate by mode) and reranker latency/precision trade-offs, measured with the built-in eval harness (clawdiney-eval).

📋 Prerequisites

Before starting, make sure you have installed:

Optional:

Configuration: BRAIN_DB_PATH env var sets the database location (default: ~/.clawdiney/brain.db). For the project knowledge graph: CARD_LLM_MODEL (Ollama model for project card Purpose/Architecture sections, default qwen3) and ENTITY_RESOLUTION_THRESHOLD (similarity cutoff for merging duplicate entities, default 0.85).

Cross-project intelligence: the project indexer builds a typed knowledge graph (dependencies, shared datastores, patterns) from your codebases. Agents can call get_project_card("name") for a project overview and how_do_projects_relate("a", "b") to see how two projects connect, with evidence.

Supported Systems:

• ✅ Linux (Ubuntu, Debian, Fedora, Arch, etc.)
• ✅ macOS (Intel and Apple Silicon)
• ✅ WSL2 (Windows Subsystem for Linux)
• ✅ BSD (FreeBSD, OpenBSD - with manual adjustments)

🛠️ Quick Installation

Option A: pip install (recommended for using Clawdiney against your own vault)

pip install clawdiney
# optional: pip install clawdiney[rerank]

Create a .env in the directory you'll run commands from (or export the same variables in your shell) — see .env.example for the full list:

VAULTS_DIR=~/clawdiney-vaults
MCP_DEFAULT_VAULT=general
BRAIN_DB_PATH=~/.clawdiney/brain.db
MODEL_NAME=bge-m3:latest

This installs three console scripts: clawdiney (vault management — see Provisioning Project Vaults below), clawdiney-index (index a vault into brain.db), and clawdiney-mcp (the MCP server entry point, used in MCP Client Configuration). Ollama still needs to be running separately with the bge-m3 model pulled.

ollama pull bge-m3
clawdiney-index

OpenAI embeddings without an Ollama service

Install the optional SDK and configure a new database path when switching from an existing Ollama index:

python3 -m venv ~/.clawdiney/openai-venv
~/.clawdiney/openai-venv/bin/python -m pip install 'clawdiney[openai]'
export VAULT_PATH=/absolute/path/to/your/ObsidianVault
export BRAIN_DB_PATH="$HOME/.clawdiney/openai-brain.db"
export EMBEDDING_PROVIDER=openai
export MODEL_NAME=text-embedding-3-small
export EMBEDDING_DIMENSION=1536
export ENABLE_RERANK=false
# Set OPENAI_API_KEY in this shell using your preferred secret manager.
~/.clawdiney/openai-venv/bin/clawdiney-index
~/.clawdiney/openai-venv/bin/python -m clawdiney.query_engine "a term in your vault"

text-embedding-3-small returns 1536 dimensions by default. The vault note text sent for indexing, and search queries sent for retrieval, go to the OpenAI API. Choose and inspect the vault before indexing; keep secrets out of notes and MCP config files. Project cards still include deterministic stack and interface information, but their generated Purpose/Architecture sections and semantic entity extraction are unavailable without Ollama. The core package still installs the Ollama Python client for its default local mode; no Ollama service or model is required for the OpenAI mode.

The MCP client must launch clawdiney-mcp with the same non-secret environment values and OPENAI_API_KEY available in its process environment. Use the absolute executable path from the venv above. Restart the agent after changing its environment or MCP configuration.

Option B: clone from source (recommended for contributing or running the bootstrapper)

git clone git@github.com:elaranjo/clawdiney.git
cd clawdiney

Configure .env:

cp .env.example .env
nano .env

Run the Bootstrapper:

chmod +x scripts/setup_brain.sh
./scripts/setup_brain.sh

📋 What the Bootstrapper Does

The setup_brain.sh script automatically executes:

🏗️ Multi-Vault Architecture

How Vaults Work

Clawdiney discovers vaults by scanning subdirectories in VAULTS_DIR (default: ~/clawdiney-vaults/). Each subdirectory must contain a clawdiney.toml config file.

clawdiney.toml format

Each vault requires a minimal config file:

id = "Payments"
name = "Payments"
description = "Payments service"
linked_vaults = ["general"]

CWD Auto-Detection (Convention > Configuration)

When you call any MCP tool without specifying vault=, Clawdiney inspects your current working directory. It walks the path backwards until it finds a directory name matching a vault id.

Linking & Fallback Chain

Vaults can link to related vaults for broader search results:

Payments-SDK ──linked_to──► [general, Payments]
                                  │
Auth-SDK     ──linked_to──► [general, Auth]
                                  │
clawdiney    ──linked_to──► []   (isolated — no fallback)

When searching, Clawdiney queries: current vault → linked vaults (in order) → general. Results from all sources are merged and deduplicated.

Using Your Personal Vault as general

To make your personal Obsidian vault the fallback general vault, create a symlink:

# Create clawdiney.toml inside your personal vault
cat >> /path/to/ObsidianVault/clawdiney.toml << 'EOF'
id = "general"
name = "General"
description = "Personal Obsidian vault - general knowledge"
linked_vaults = []
EOF

# Create symlink
ln -sfn /path/to/ObsidianVault ~/clawdiney-vaults/general

# Reindex
OLLAMA_HOST= ./venv/bin/python3 -m clawdiney.indexer

Provisioning Project Vaults

For teams with multiple projects, use the provisioning script to scan a projects directory and create vaults automatically:

./scripts/provision_project_vaults.sh

This scans ~/projetos/ and creates a vault per project with:

• Auto-generated clawdiney.toml (SDKs linked to parent, clawdiney isolated)
• P.A.R.A. folder structure (00_Inbox, 10_Projects, 20_Areas, 30_Resources, 40_Archives, 50_Daily)
• Project analysis files (README, Architecture, API docs, Domain model)

🔌 MCP Client Configuration

Clawdiney runs as a local Python process (stdio transport) — no server to start separately, no container. Your MCP client (Claude Code, OpenCode, etc.) launches it on demand.

The command/args differ depending on how you installed Clawdiney: a pip install exposes clawdiney-mcp directly on PATH; a clone + bootstrapper setup runs the module from its venv instead. Pick the block matching Option A or B above.

Claude Code (~/.claude.json, project scope):

{
  "projects": {
    "/home/YOUR_PROJECTS_DIR": {
      "mcpServers": {
        "clawdiney": {
          "command": "clawdiney-mcp",
          "env": {
            "VAULTS_DIR": "/path/to/your/vaults",
            "MCP_DEFAULT_VAULT": "general",
            "MODEL_NAME": "bge-m3:latest",
            "ENABLE_RERANK": "true"
          }
        }
      }
    }
  }
}

Cloned from source instead? Use "command": "/path/to/clawdiney/venv/bin/python3" with "args": ["-m", "clawdiney.mcp_server"].

OpenCode (opencode.json):

{
  "mcp": {
    "clawdiney": {
      "type": "local",
      "command": ["clawdiney-mcp"],
      "enabled": true,
      "environment": {
        "VAULTS_DIR": "/path/to/your/vaults",
        "MCP_DEFAULT_VAULT": "general",
        "MODEL_NAME": "bge-m3:latest",
        "ENABLE_RERANK": "true"
      }
    }
  }
}

Cloned from source instead? Use "command": ["/path/to/clawdiney/venv/bin/python3", "-m", "clawdiney.mcp_server"].

Restart the client session after registering — MCP config is read once at session start.

Remote/network access (SSE transport) is still available by setting MCP_TRANSPORT=sse before launching clawdiney.mcp_server directly, but stdio (the default, no config needed) is what both clients above use and is the supported path.

🔍 Proactive Context Hook (Optional)

scripts/claude_hook_context.py is a Claude Code UserPromptSubmit hook: it runs search_brain-equivalent retrieval before every prompt and injects the results as context automatically, so relevant SOPs/patterns surface even if the agent doesn't think to search for them.

Install — add to ~/.claude/settings.json under hooks.UserPromptSubmit:

{
  "hooks": [
    {
      "type": "command",
      "command": "/path/to/clawdiney/venv/bin/python3 /path/to/clawdiney/scripts/claude_hook_context.py",
      "timeout": 10,
      "statusMessage": "Querying clawdiney brain..."
    }
  ]
}

Controlling how many sources it injects (default: 3; 0 disables it entirely):

Precedence: inline @nN marker > CLAWDINEY_HOOK_N_RESULTS > default (3).

🚀 Usage

Ensure Ollama Is Running

Clawdiney's only external dependency is Ollama (for embeddings, and card-generation LLM calls). Everything else — vectors, full-text search, and the knowledge graph — lives in a single embedded SQLite file (brain.db, default ~/.clawdiney/brain.db). No services to start or stop.

ollama serve   # if not already running as a daemon
ollama pull bge-m3

Index Your Vault(s)

./venv/bin/python3 -m clawdiney.indexer

Via MCP Client (Recommended)

With MCP configured, the agent has access to read and write tools:

Read Tools (Discovery)

• search_brain(query, vault?, agent_id?, n_results?) - Hybrid search (BM25 + vector, RRF-fused, optionally reranked) for architectural patterns, SOPs, and design system components. agent_id (optional) also searches that agent's own memory (see write_memory below) alongside shared vault content; results append an "Unresolved conflicts" section when a returned note touches a contradicted fact. n_results (optional, default 3) sets how many results to retrieve — raise it (6-8) for broad/exploratory questions spanning multiple docs, lower it (1-2) for a narrow lookup where you already know which note has the answer; n_results=0 explicitly skips the search instead of returning a real (possibly empty) result set
• explore_graph(note_name, vault?, agent_id?) - Find entities related to a note or project — notes, WikiLinks, tags, or (for projects) dependencies/patterns — with relation type and evidence. Same agent_id scoping and conflict surfacing as search_brain
• resolve_note(name) - Resolve ambiguous note names into canonical vault-relative paths
• get_note_chunks(path) - Inspect indexed chunk headers for a resolved note
• get_project_card(name) - Full project card (Purpose, Stack, Architecture, Interfaces) — the first call when touching an unfamiliar project
• how_do_projects_relate(a, b, vault?, agent_id="*") - Graph paths between two projects (shared dependencies, datastores, patterns) with evidence. agent_id="*" (default) applies no filtering; pass a specific id to additionally restrict to that agent's own relations
• health_check() - Check health of brain.db, Ollama, and the optional reranker, plus per-vault document counts

Write Tools (Knowledge Capture)

• write_note(path, content, mode) - Create or update a note at any vault location
• write_memory(fact, source, agent_id="default", vault?) - Persist a natural-language fact (ideally "<Subject> <verb> <value>", e.g. "User prefers embedded SQLite over Docker-based stacks") as agent-written memory. Resolves the subject against existing entities and writes to a provenance-marked 40_Memory/ note — the only write tool triggered by conversational knowledge rather than an explicit save request
• append_to_daily(content) - Append content to today's daily note (50_Daily/YYYY-MM-DD.md)
• add_learning(topic, content, area) - Save learnings to appropriate folder (SOPs, Architecture, etc.)
• delete_note(path) - Delete a note and remove from index

Example Workflow:

"Check in the Brain if there are any SOPs for production deployment." → Found existing SOP, update it: write_note("30_Resources/SOPs/SOP_Deploy.md", updated_content, mode="overwrite")

"Search the brain for UI Design System patterns." → No pattern found, create new: add_learning("Button_Component", "# Design System\\n\\nButton patterns...", area="DesignSystem")

"Document today's learnings about the project." → append_to_daily("## Learnings\\n- Discovered X about the architecture")

"Remember that I prefer embedded SQLite over Docker-based stacks for this kind of tool." → write_memory("User prefers embedded SQLite over Docker-based stacks", source="conversation")

Full-file reading is intentionally outside the MCP workflow. The agent should use the repository or vault filesystem directly after search_brain has identified the relevant note.

Via Shell (Alternative)

If MCP is not available, use the direct script:

./scripts/ask_brain.sh "production deployment patterns"

Via Python (For developers)

./venv/bin/python3 -m clawdiney.query_engine "your query here"

🧩 Architecture

┌─────────────────────────────────────────────────────────┐
│                AI Agent (Claude Code, OpenCode, etc.)    │
└────────────────────────┬────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         ▼
┌─────────────────────────────────────────────────────────┐
│              Clawdiney MCP Server                        │
│  ┌──────────────────────────────┐ ┌──────────────────┐  │
│  │      Hybrid Query Engine     │ │  Vault Detector  │  │
│  │  BM25 (FTS5) + Vector (KNN)  │ │  (CWD-based)     │  │
│  │  → RRF fusion → rerank       │ │  → vault_id      │  │
│  └───────────────┬──────────────┘ └──────────────────┘  │
└──────────────────┼───────────────────────────────────────┘
                    ▼
┌─────────────────────────────────────────────────────────┐
│         brain.db (single embedded SQLite file)           │
│  documents · chunks · chunk_vectors (sqlite-vec)          │
│  chunk_fts (FTS5) · entities · relations (graph)          │
└─────────────────────────────────────────────────────────┘
                    ▲
                    │ indexed from
┌─────────────────────────────────────────────────────────┐
│              VAULTS_DIR (~/clawdiney-vaults/)            │
│                                                         │
│  general/ (personal vault)   clawdiney/ (this project)  │
│  Each vault has: clawdiney.toml + P.A.R.A. structure    │
└─────────────────────────────────────────────────────────┘

Only external dependency: Ollama (embeddings + card-generation LLM calls). No Docker, no separate vector/graph/cache servers.

📁 Project Structure

clawdiney/
├── src/clawdiney/             # Main Python package
│   ├── __init__.py            # Package exports
│   ├── config.py              # Multi-vault configuration, VAULTS_DIR discovery, BRAIN_DB_PATH
│   ├── vault_config.py        # VaultConfig dataclass + clawdiney.toml parser
│   ├── storage.py             # Embedded brain.db gateway (sqlite-vec + FTS5 + graph tables)
│   ├── indexer.py             # Full indexing into brain.db
│   ├── incremental_indexer.py # Incremental sync (content hashes stored in brain.db)
│   ├── query_engine.py        # Hybrid search (BM25 + vector, RRF fusion) + vault fallback chain
│   ├── reranker.py            # Cross-encoder reranking (optional extra, GPU→CPU fallback)
│   ├── embedding_providers.py # EmbeddingProvider protocol (Ollama default, OpenAI optional)
│   ├── vault_writer.py        # Thread-safe write operations per vault
│   ├── mcp_server.py          # MCP server: CWD auto-detection, search/graph/write tools
│   ├── project_indexer.py     # Analyzes codebases → enriched project cards for Obsidian
│   ├── project_index_config.py# Selective file indexing patterns (include/exclude)
│   ├── entity_extractor.py    # Project knowledge graph: manifest parsing + LLM extraction
│   ├── chunking.py            # Text chunking strategies
│   ├── constants.py           # Application constants
│   ├── logging_config.py      # Logging setup
│   ├── cli.py                 # CLI entry point (vault create/list)
│   └── scripts/
│       ├── watch_vault.py     # File watcher for real-time vault sync
│       ├── sync_vault.py      # Manual sync script (per-vault aware)
│       ├── watch_projects.py  # File watcher for codebase → project card sync
│       └── index_projects.py  # CLI: index projects to Obsidian
│
├── tests/                     # Test suite (pytest, no service mocks — real tempfile SQLite)
│   ├── test_storage.py
│   ├── test_query_engine.py
│   ├── test_hybrid_search.py
│   ├── test_reranker.py
│   ├── test_entity_extractor.py
│   ├── test_mcp_server.py
│   └── ...
│
├── scripts/                   # Shell scripts
│   ├── setup_brain.sh         # Bootstrap setup (venv, deps, pull embedding model, index)
│   ├── ask_brain.sh           # Query from command line
│   ├── run_tests.sh           # Run test suite
│   ├── claude_hook_context.py # Optional Claude Code UserPromptSubmit hook (proactive context)
│   ├── provision_project_vaults.sh
│   └── ...
│
├── .env.example                # Environment template with multi-vault setup
├── pyproject.toml               # Python project configuration (source of truth for dependencies)
└── README.md                    # This file

🔄 Updating Knowledge

Good news: Clawdiney now has automatic sync! No need to manually re-index.

Auto-Sync (Default)

The MCP server automatically checks for vault changes on startup and syncs any modified files.

Real-Time Watcher (Optional)

For active development, run the file watcher that syncs changes in real-time:

./venv/bin/python3 -m clawdiney.scripts.watch_vault

Manual Sync (On-Demand)

# Check sync status
./venv/bin/python3 -m clawdiney.scripts.sync_vault --status

# Incremental sync (only changed files)
./venv/bin/python3 -m clawdiney.scripts.sync_vault

# Full sync (reindex everything)
./venv/bin/python3 -m clawdiney.scripts.sync_vault --full

The agent has immediate access to new/modified notes after sync completes.

🛡️ Privacy and Security

• Multi-Vault Isolation: Each project's data stays in its own directory under VAULTS_DIR. No vault reads another vault's .md files.
• Symlink Support: You can symlink a vault directory, allowing you to keep your personal vault in one location while Clawdiney references it.
• Local Data: Everything runs locally on your machine. Nothing is sent to the cloud (except if you use cloud models).
• Single-file storage: All indexed data lives in one local SQLite file (brain.db), scoped by vault at the row level. Delete the file to wipe everything; copy it to back everything up.

🐛 Troubleshooting

Start with the MCP health_check() tool — it reports brain.db status (path, document/chunk/entity/relation counts), the selected embedding provider, and whether the reranker loaded, plus per-vault document counts. In OpenAI mode it sends a short synthetic health-check string to verify API access and vector dimension.

MCP client doesn't see the server

• Check the client config points command/args at <venv>/bin/python3 -m clawdiney.mcp_server and restart the client session (MCP config is only read at session start).
• Test the server manually: ./venv/bin/python3 -m clawdiney.mcp_server (validates the selected provider, then waits on stdio — Ctrl+C to stop).

search_brain returns nothing

• Run health_check() — if documents: 0, the vault hasn't been indexed yet: ./venv/bin/python3 -m clawdiney.indexer.
• Check VAULTS_DIR / VAULT_PATH env vars match where your .md files actually live.

"Re-index required" / SchemaMismatchError

• brain.db was created with a different embedding model or dimension than your current config. Back up that database first, then set a new BRAIN_DB_PATH and run clawdiney-index to build a fresh index. Do not delete the old database to make the error disappear.

Reranker doesn't activate

• Check it's installed: pip install clawdiney[rerank] (adds sentence-transformers, ~2GB with model weights).
• On small/shared GPUs, the reranker automatically retries on CPU if CUDA runs out of memory — check the logs for "retrying on CPU". If it still fails, set ENABLE_RERANK=false to skip it entirely; search still works via BM25+vector RRF fusion.

Reranker configuration

RERANK_MODEL selects the cross-encoder (default BAAI/bge-reranker-v2-m3, ~568M params). Any sentence-transformers-compatible cross-encoder works — e.g. a smaller/faster one:

RERANK_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2

Measured with clawdiney-eval --mode hybrid --rerank against the fixture vault (CPU fallback, 8 queries, warm model):

On this small fixture both models score identically, so the numbers only show the latency delta — they don't prove the smaller model preserves precision on a larger, harder vault. Before adopting a non-default RERANK_MODEL, re-run clawdiney-eval --all-modes against your own vault (or an expanded golden set) and compare against the current baseline (tests/eval/baseline.json) rather than trusting these numbers directly.

Ollama connection error

• Confirm Ollama is running: ollama list. Start it with ollama serve if not.
• Confirm the embedding model is pulled: ollama pull bge-m3.

📚 Useful Commands

# Check brain.db health (documents/chunks/entities/relations, Ollama, reranker)
# via any MCP client, or directly:
./venv/bin/python3 -c "from clawdiney.storage import get_storage; print(get_storage().stats())"

# Index all configured vaults
./venv/bin/python3 -m clawdiney.indexer

# Check sync status
./venv/bin/python3 -m clawdiney.scripts.sync_vault --status

# Incremental sync (only changed files)
./venv/bin/python3 -m clawdiney.scripts.sync_vault

# Full sync (reindex everything)
./venv/bin/python3 -m clawdiney.scripts.sync_vault --full

# Real-time file watcher
./venv/bin/python3 -m clawdiney.scripts.watch_vault

# Test search from the command line
./scripts/ask_brain.sh "your query"

❓ FAQ (Frequently Asked Questions)

"Do I need Obsidian installed?"

No. Obsidian is just an editor. The Brain reads .md files directly, so you only need the Vault files.

"Can I use my personal vault?"

Yes! Use the symlink approach:

# Add clawdiney.toml to your personal vault
cat >> /path/to/your/vault/clawdiney.toml << 'EOF'
id = "general"
name = "General"
description = "Personal Obsidian vault"
linked_vaults = []
EOF

# Symlink it as the general vault
ln -sfn /path/to/your/vault ~/clawdiney-vaults/general

# Reindex
./venv/bin/python3 -m clawdiney.indexer

Your vault becomes the fallback general vault — searched whenever a more specific vault doesn't match.

"How long does indexing take?"

Initial full sync depends on vault size:

• Small vault (< 100 notes): ~30 seconds
• Medium vault (100-500 notes): 1-2 minutes
• Large vault (> 500 notes): 3-5 minutes

Incremental sync (subsequent syncs) only processes changed files and is much faster (typically 1-5 seconds per file).

"Do I need to re-index every time I update an SOP?"

No! Auto-sync handles this automatically:

• On MCP startup: Checks for changes and syncs automatically
• With Watcher mode: Syncs in real-time as you edit files
• Manual: Run python sync_vault.py for on-demand sync

"Does it work on Windows?"

Yes! Through WSL2 (Windows Subsystem for Linux):

1. Install WSL2: wsl --install (in PowerShell as Admin)
2. Install Ollama for Windows (or inside WSL2) — see ollama.com
3. Inside WSL2, follow the normal installation instructions as if it were Linux

"Which Linux distribution is recommended?"

The system has been tested mainly on Ubuntu 22.04+ and Debian 11+, but it should work on any modern distribution with Python 3.10+ and Ollama — no other OS-level requirements.

"What if I use another model instead of Qwen in Ollama?"

It works normally. The Brain is model-agnostic. You use whatever model you prefer in Claude Code. The bge-m3 is just for generating embeddings (vectors), not for answering questions.

"Can the agent write new notes automatically?"

Yes! The MCP server includes write tools:

• write_note(path, content) - Create or update any note
• append_to_daily(content) - Add to today's daily note
• add_learning(topic, content, area) - Save learnings to the right folder

When the agent learns something new during a task, it can save it directly to the vault. The change is automatically indexed and becomes searchable within seconds.

"Where should I save different types of content?"

Use the add_learning() tool which automatically routes to the correct folder:

🤝 Contributing

To add new tools to MCP:

1. Edit src/clawdiney/mcp_server.py
2. Add a new function decorated with @mcp.tool()
3. Add tests (tests/test_mcp_server.py) and run ./scripts/run_tests.sh before committing.

📄 License

MIT License

Created with ❤️ by the Voices in My Head team

Compatibility: Linux • macOS • WSL2 • Unix-like