clawmem 0.13.0 → 0.15.0

package/docs/internals/entity-resolution.md

@@ -0,0 +1,135 @@
+# Entity resolution
+
+ClawMem extracts named entities from documents during A-MEM enrichment, resolves them to canonical forms, and tracks co-occurrences to power entity-aware retrieval.
+
+## Extraction
+
+Each document is passed to the LLM (QMD query expansion model by default) with a prompt requesting named entities as JSON. The LLM returns `(name, type)` pairs from a fixed type vocabulary:
+
+`person`, `project`, `service`, `tool`, `concept`, `org`, `location`
+
+Entities pass through quality filters before storage:
+- Document titles are rejected (Levenshtein similarity > 0.85 against the doc's own title)
+- Names longer than 60 characters are rejected (likely titles or sentence fragments)
+- Template placeholders and heading labels are blocklisted
+- Location entities are validated against lexical patterns (IP addresses, VM identifiers, short geographic names) — long non-geographic names typed as location are rejected
+
+## Canonical resolution
+
+When an entity is extracted, ClawMem checks whether a matching entity already exists in the vault. Resolution uses FTS5 candidate lookup followed by Levenshtein fuzzy matching (threshold 0.75, lowered to 0.65 for person names).
+
+Resolution is **type-agnostic within compatibility buckets**. Two entities with the same name but different types will merge if their types belong to the same bucket:
+
+| Bucket | Types | Rationale |
+|--------|-------|-----------|
+| `person` | person | People should never merge with non-people |
+| `org` | org | Organizations are distinct from other categories |
+| `location` | location | Geographic entities kept separate |
+| `tech` | project, service, tool, concept | LLMs frequently assign these inconsistently for the same entity across documents |
+
+Cross-bucket merges are always rejected. "Andrea" as a person will never merge with "Andrea" as a project, even if both exist in the vault.
+
+Unknown types (if you customize the extraction prompt) default to their own isolated bucket — they won't false-merge with anything.
+
+### How merging works
+
+When a new entity is extracted and a canonical match is found in the same bucket:
+1. The existing entity's `mention_count` is incremented
+2. The new mention is recorded against the existing entity's ID
+3. No new `entity_nodes` row is created
+
+When no match is found, a new entity node is created with ID format `vault:type:normalized_name`.
+
+### Extending the type vocabulary
+
+The extraction prompt and bucket map live in `src/entity.ts`. To add domain-specific types:
+
+1. Add the type to the prompt's type list
+2. Add it to `ENTITY_BUCKETS` with a bucket assignment:
+
+```typescript
+const ENTITY_BUCKETS: Record<string, string> = {
+  person: 'person',
+  org: 'org',
+  location: 'location',
+  project: 'tech',
+  service: 'tech',
+  tool: 'tech',
+  concept: 'tech',
+  // Domain extensions:
+  statute: 'legal',
+  regulation: 'legal',   // statutes and regulations can merge
+  drug: 'medical',
+  condition: 'medical',  // or keep them separate with distinct buckets
+};
+```
+
+Types not listed in `ENTITY_BUCKETS` automatically form their own single-type bucket.
+
+## Co-occurrences
+
+When multiple entities are extracted from the same document, all pairs are recorded in `entity_cooccurrences`. This powers:
+- The entity graph channel in `query` (conditional 1-hop entity walk from seed results)
+- Entity-aware MPFP meta-path patterns (`[entity, semantic]`)
+- `getEntityGraphNeighbors()` for discovering related documents through shared entities
+
+## Entity edges
+
+Document-to-document edges with `relation_type='entity'` are created in `memory_relations` when two documents share entities. Edge weight is computed using IDF-based specificity:
+
+- **Rare entities** (appearing in few documents) produce higher-weight edges
+- **Ubiquitous entities** (appearing in many documents) produce low-weight edges that fall below the creation threshold
+
+This prevents common entities (e.g., a project name mentioned in every doc) from creating noise edges between unrelated documents, while allowing rare entities to establish meaningful connections even as the sole shared entity.
+
+## Enrichment lifecycle
+
+Entity extraction runs as part of the A-MEM `postIndexEnrich()` pipeline during indexing. Each document's enrichment is tracked via `entity_enrichment_state` (input hash of title + body). Documents are only re-extracted when their content changes.
+
+To force re-extraction after upgrading ClawMem:
+
+```bash
+clawmem reindex --enrich
+```
+
+This processes all documents through the full enrichment pipeline regardless of whether content changed.
+
+## Model quality and entity extraction
+
+Entity extraction quality scales directly with LLM capability. The default QMD query expansion model (1.7B parameters) is optimized for query expansion, not structured extraction — it can mistype entities, echo prompt examples, or extract document titles as entities. The quality filters in the pipeline catch most of these, but a more capable model produces cleaner extractions with fewer filter rejections.
+
+**Options for better entity extraction:**
+
+### Option 1: Use a larger local model
+
+Point `CLAWMEM_LLM_URL` at a more capable model for all LLM tasks (query expansion + entity extraction + A-MEM notes):
+
+```bash
+# Example: use a 7B+ model instead of QMD 1.7B
+CLAWMEM_LLM_URL=http://localhost:8091 \
+CLAWMEM_LLM_MODEL=your-7b-model \
+clawmem reindex --enrich
+```
+
+Trade-off: query expansion is already well-served by QMD — a larger model is slower for the same task with marginal gains. Entity extraction benefits more.
+
+### Option 2: Use a cloud API
+
+Point the LLM at a cloud endpoint for higher-quality extraction. Any OpenAI-compatible `/v1/chat/completions` endpoint works:
+
+```bash
+# Example: use an OpenAI-compatible API
+CLAWMEM_LLM_URL=https://api.example.com/v1 \
+CLAWMEM_LLM_MODEL=gpt-5.4-mini \
+clawmem reindex --enrich
+```
+
+Trade-off: cloud API calls have per-token costs. With 261 documents at ~2000 tokens each, a full re-enrichment is roughly 500K input tokens.
+
+### Option 3: Accept the default and rely on filters
+
+The quality filters (title rejection, length limits, blocklist, location validation, type-agnostic canonical resolution) compensate for most small-model weaknesses. For many vaults, the default QMD model with filters produces adequate entity graphs. Run `reindex --enrich` after upgrading ClawMem to benefit from improved filters.
+
+### Recommendation
+
+For vaults where entity graph quality matters (large corpora, cross-document discovery, ENTITY intent queries), use a 7B+ model or cloud API for the initial `reindex --enrich` pass. The watcher's incremental enrichment can continue with the default QMD model — individual document additions are less sensitive to extraction quality than bulk corpus enrichment.

package/docs/internals/graph-traversal.md

@@ -0,0 +1,85 @@
+# Graph traversal in ClawMem
+
+ClawMem maintains a multi-graph of relationships between documents in the `memory_relations` table. These edges let agents trace chains of reasoning across documents — answering questions like "why did we decide X", "what caused Y", and "what else supports Z" that keyword and vector search alone can't handle.
+
+Most edges are created automatically during indexing (A-MEM link generation) and after each response (causal inference from decision-extractor). The `build_graphs` tool adds temporal backbone and bulk semantic edges for vaults with sparse A-MEM coverage. You don't need to manage the graph manually under normal use.
+
+## Edge types
+
+| Type | Meaning | Direction |
+|------|---------|-----------|
+| `semantic` | Topically related (cosine similarity or LLM-assessed) | Bidirectional |
+| `supporting` | One document supports/reinforces another | Directional |
+| `contradicts` | One document contradicts another | Directional |
+| `causal` | One event/decision caused or led to another | Directional |
+| `temporal` | Creation-order adjacency | Directional |
+
+## How edges are created
+
+| Source | Edge types | Trigger |
+|--------|-----------|---------|
+| **A-MEM `generateMemoryLinks()`** | semantic, supporting, contradicts | Indexing (new docs only). LLM-assessed confidence + reasoning. Requires embeddings for neighbor discovery. |
+| **A-MEM `inferCausalLinks()`** | causal | Post-response (`decision-extractor`). Links between `_clawmem/agent/observations/` docs. |
+| **Beads `syncBeadsIssues()`** | causal, supporting, semantic | `beads_sync` MCP tool or watcher. Maps dependency types: `blocks→causal`, `discovered-from→supporting`, `relates-to→semantic`. |
+| **`buildTemporalBackbone()`** | temporal | `build_graphs` MCP tool (manual). Creation-order edges between all active docs. |
+| **`buildSemanticGraph()`** | semantic | `build_graphs` MCP tool (manual). Pure cosine similarity between embeddings. |
+
+### SPO knowledge graph (entity_triples)
+
+Separate from `memory_relations`, the `entity_triples` table stores structured Subject-Predicate-Object facts with temporal validity (`valid_from`/`valid_to`). Triples are emitted by the observer LLM as `<triples>` blocks alongside `<facts>`, parsed and validated by `parseObservationXml` against a tight canonical predicate vocabulary, then persisted by `decision-extractor` using canonical `vault:type:slug` entity IDs via `ensureEntityCanonical`.
+
+**Eligible observation types** for triple extraction: decision, preference, milestone, problem, discovery, feature. Observation types `bugfix`, `change`, `refactor` are excluded as secondary safety net.
+
+**Canonical predicate vocabulary** (parser rejects anything outside this set): `adopted`, `migrated_to`, `deployed_to`, `runs_on`, `replaced`, `depends_on`, `integrates_with`, `uses`, `prefers`, `avoids`, `caused_by`, `resolved_by`, `owned_by`. The `prefers` and `avoids` predicates store their object as a literal (not resolved to an entity).
+
+**Entity type inheritance** is ambiguity-safe via `resolveEntityTypeExact`: if exactly one active entity in the vault shares the name, its type is inherited; zero matches or multiple matches (cross-bucket ambiguity) default to `concept`.
+
+**Provenance**: each triple's `source_doc_id` points at the persisted observation document it was extracted from. Triples for observations whose doc insert failed are naturally skipped because the extractor iterates the `ObservationWithDoc` array.
+
+Query via the `kg_query(entity)` MCP tool — accepts either an entity name (resolved via `searchEntities`) or a canonical ID in `vault:type:slug` form. This is not used by `adaptiveTraversal()` — it serves a different purpose (structured entity lookup vs document graph traversal).
+
+### Edge collision
+
+Both `generateMemoryLinks()` and `buildSemanticGraph()` insert `semantic` edges. The primary key is `(source_id, target_id, relation_type)` — first writer wins (`INSERT OR IGNORE`). A-MEM edges take precedence if they exist.
+
+## Adaptive traversal
+
+`adaptiveTraversal()` performs multi-hop beam search:
+
+1. Start from anchor nodes (top search results)
+2. At each hop, expand outbound edges (all types) and inbound edges (semantic + entity only)
+3. Score candidates by:
+   - Edge weight (confidence)
+   - Cosine similarity to the query embedding
+   - Decay by depth
+4. Beam selection: keep top `beamWidth` candidates per hop
+5. Budget cap: stop after visiting `budget` total nodes
+
+### Traversal asymmetry
+
+| Direction | Edge types traversed |
+|-----------|---------------------|
+| Outbound (source→target) | All: semantic, supporting, contradicts, causal, temporal |
+| Inbound (target→source) | Only: semantic, entity |
+
+This is intentional — temporal and causal edges are directional by nature.
+
+## When to run build_graphs
+
+- After **bulk ingestion** (many new docs at once) — adds temporal backbone and fills semantic gaps
+- When `intent_search` returns **weak or incomplete results** and you suspect graph sparsity
+- Do NOT run after every reindex — A-MEM creates per-doc links automatically for new docs
+
+## When to run find_causal_links
+
+Use after `intent_search` to walk the full causal chain from a specific document:
+
+```
+# 1. Find the anchor
+intent_search("why did we switch to PostgreSQL")
+# → top result: decisions/2026-02-15-db-migration.md (#a1b2c3)
+
+# 2. Trace the chain
+find_causal_links(docid="#a1b2c3", direction="both", depth=5)
+# → shows what caused this decision and what it caused
+```

package/docs/internals/intent-search-pipeline.md

@@ -0,0 +1,103 @@
+# Intent search pipeline
+
+The `intent_search` MCP tool classifies query intent and uses graph traversal to find causal chains across AI agent memory that keyword and vector search alone can't reach.
+
+## Pipeline stages
+
+```
+User Query
+  │
+  ▼
+Intent Classification (LLM)
+  │ → WHY, WHEN, ENTITY, or WHAT
+  │ (or force_intent override)
+  │
+  ▼
+Baseline Search
+  │ BM25 + Vector in parallel
+  │
+  ▼
+Intent-Weighted RRF
+  │ WHY  → boost vector [1.0, 1.5]
+  │ WHEN → boost BM25   [1.5, 1.0]
+  │ Other → balanced     [1.0, 1.0]
+  │
+  ▼
+Graph Traversal (WHY/ENTITY only)
+  │ Multi-hop beam search over memory_relations
+  │ Outbound: all edge types
+  │ Inbound: semantic + entity only
+  │ Budget: 30 nodes, depth: 2, beam: 5
+  │ Scores normalized to [0,1]
+  │
+  ▼
+Cross-Encoder Reranking
+  │ 200 chars/doc context
+  │ File-keyed score join
+  │
+  ▼
+Position-Aware Blending
+  │ origWeight · upstream score + (1 − origWeight) · rerank
+  │ origWeight = 0.75 (top 3), 0.60 (mid), 0.40 (tail)
+  │ (intent_search keeps this curve; the query tool uses blendRerank instead)
+  │
+  ▼
+Composite Scoring
+  │
+  ▼
+Results (with intent + confidence metadata)
+```
+
+## Intent types
+
+| Intent | Signal | Graph traversal | RRF weighting |
+|--------|--------|----------------|---------------|
+| WHY | "why did", "what caused", "reason for", "decided to" | Yes | Boost vector |
+| WHEN | "when did", "first/last occurrence", timeline | No | Boost BM25 |
+| ENTITY | Named component/person/service needing cross-doc linkage | Yes | Balanced |
+| WHAT | General factual | No | Balanced |
+
+## Graph traversal
+
+When intent is WHY or ENTITY, the pipeline runs `adaptiveTraversal()`:
+
+1. Anchors on top 10 search results
+2. Traverses `memory_relations` edges:
+   - **Outbound** (source→target): semantic, supporting, contradicts, causal, temporal
+   - **Inbound** (target→source): semantic and entity only
+3. Beam search with query embedding as relevance signal
+4. Discovered nodes are hydrated from the database and merged with search results
+5. Scores are normalized to [0, 1] before merging
+
+## Graph edge sources
+
+| Source | Edge types | How populated |
+|--------|-----------|--------------|
+| A-MEM `generateMemoryLinks()` | semantic, supporting, contradicts | During indexing (new docs) |
+| A-MEM `inferCausalLinks()` | causal | Post-response (decision-extractor) |
+| Beads `syncBeadsIssues()` | causal, supporting, semantic | `beads_sync` or watcher |
+| `buildTemporalBackbone()` | temporal | `build_graphs` (manual) |
+| `buildSemanticGraph()` | semantic | `build_graphs` (manual) |
+
+## Differences from query
+
+| Aspect | `query` | `intent_search` |
+|--------|---------|-----------------|
+| Query expansion | Yes | No |
+| Intent hint | Manual (`intent` param) | Auto-detected |
+| Rerank context | 4000 chars/doc | 200 chars/doc |
+| Graph traversal | No | Yes (WHY/ENTITY) |
+| MMR diversity | Yes | No |
+| `compact` param | Yes | No |
+| `collection` filter | Yes | No |
+| Best for | General recall | Causal chains spanning docs |
+
+## When to use
+
+Use `intent_search` **directly** (not as a fallback from query) when:
+- The question starts with "why"
+- You need to trace decision chains
+- You're asking about entity relationships across documents
+- You need temporal context ("when did this change")
+
+For WHEN queries, start with `enable_graph_traversal=false` (BM25-biased). Fall back to `query()` if recall drifts.

package/docs/internals/query-pipeline.md

@@ -0,0 +1,100 @@
+# Query pipeline
+
+The `query` MCP tool runs the full hybrid retrieval pipeline, combining BM25, vector search, query expansion, and cross-encoder reranking in a single call.
+
+## Pipeline stages
+
+```
+User Query + optional intent hint
+  │
+  ▼
+BM25 Probe
+  │ Top hit score >= 0.85 with gap >= 0.15?
+  │ (disabled when intent is provided)
+  ├── YES → Skip expansion, use BM25 results directly
+  │
+  ▼
+Query Expansion (LLM)
+  │ Generates text variants (lex/vec/hyde)
+  │ Intent steers the expansion prompt
+  │
+  ▼
+Parallel Search (typed routing)
+  │ BM25(original) + Vector(original)   ← original fans out to both
+  │ + BM25(lex expansions)              ← lex → BM25 only
+  │ + Vector(vec/hyde expansions)       ← vec/hyde → vector only
+  │
+  ▼
+Reciprocal Rank Fusion (k=60)
+  │ Original query lists get 2x positional weight
+  │ Expanded query lists get 1x weight
+  │ Top candidateLimit results (default 30)
+  │
+  ▼
+Intent-Aware Chunk Selection
+  │ Intent terms at 0.5x weight
+  │ Query terms at 1.0x weight
+  │
+  ▼
+Cross-Encoder Reranking
+  │ 4000 char context per doc
+  │ Intent prepended to rerank query
+  │ Chunk dedup (identical texts share single call)
+  │ Batch cap = 4
+  │
+  ▼
+Rerank / RRF Blend (blendRerank)
+  │ 0.9 · reranker + 0.1 · normalized-RRF tiebreaker
+  │ Reranker is the dominant signal; can promote a doc over RRF #1
+  │ Falls back to pure RRF order if the reranker is unavailable / degenerate
+  │ (no score above RERANK_DEGENERATE_FLOOR ≈ 1e-4); emits a rate-limited warning on fallback
+  │ (the reranker-health guard surfaces this — see `clawmem doctor` / `clawmem rerank-health`)
+  │
+  ▼
+Composite Scoring
+  │ (relevance * 0.70 + recency * 0.15 + confidence * 0.15)   ← query-tuned weights (v0.13.0)
+  │ recency-intent queries instead use 0.10 / 0.70 / 0.20
+  │ × quality multiplier × co-activation boost
+  │
+  ▼
+MMR Diversity Filter
+  │ Jaccard bigram similarity > 0.6 → demoted
+  │
+  ▼
+Results
+```
+
+## Key parameters
+
+| Parameter | Effect | Default |
+|-----------|--------|---------|
+| `intent` | Steers 5 stages: expansion, reranking, chunk selection, snippet extraction, bypass | — |
+| `candidateLimit` | How many candidates reach reranking | 30 |
+| `compact` | Snippet vs full content output | true |
+| `collection` | Filter by collection (comma-separated) | all |
+
+## BM25 strong-signal bypass
+
+When the top BM25 hit scores >= 0.85 and the gap to the second hit is >= 0.15, the pipeline skips query expansion entirely. This is a fast path for queries with obvious keyword matches.
+
+The bypass is disabled when `intent` is provided — intent implies the query is ambiguous, so keyword confidence alone is insufficient.
+
+## Query expansion
+
+The LLM generates lex (keyword), vec (semantic), and hyde (hypothetical answer) variants of the query, each carried as a typed `ExpandedQuery`. Variants are **routed by type**: `lex` expansions are searched on BM25 only, `vec` and `hyde` on vector only. The original query is the only leg that fans out to *both* backends. All legs are searched in parallel and fused; the original query's two lists receive 2x weight in RRF, ensuring it anchors the ranking.
+
+Routing by type matters because a keyword expansion ("auth token refresh") is useless to a dense vector model, and a hypothetical-answer passage (hyde) is mostly stopword noise to BM25. Searching every variant on both backends — the earlier behavior — fed each leg the input it handles worst, diluting RRF with low-quality lists.
+
+## Chunk selection
+
+For reranking, each document's content is windowed into overlapping chunks. Chunks are scored by overlap with query terms (1.0x weight) and intent terms (0.5x weight). The best chunk per document is sent to the cross-encoder.
+
+## When to use query vs alternatives
+
+| Tool | Cost | When |
+|------|------|------|
+| `search` | 0 GPU calls | Known exact terms, spot-check |
+| `vsearch` | 1 GPU call | Conceptual, don't know vocabulary |
+| `query` | 3+ GPU calls | General recall, unsure which signal matters |
+| `intent_search` | Hybrid + graph | Why/entity chains, temporal queries |
+| `query_plan` | Hybrid + decomposition | Multi-topic queries |

package/docs/introduction.md

@@ -0,0 +1,104 @@
+# ClawMem overview
+
+ClawMem is an open-source memory engine for Claude Code and AI agents. It runs on-device, giving agents persistent and searchable memory that survives across sessions, compactions, and runtime boundaries. The system integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client including OpenClaw), or a native OpenClaw memory plugin (`kind: memory`, v0.10.0+).
+
+## What it does
+
+- **Indexes** markdown documents into a local SQLite vault with full-text search (BM25) and vector embeddings
+- **Retrieves** relevant context automatically via hooks or on-demand via MCP tools / REST API
+- **Scores** results using composite scoring (relevance, recency, confidence, quality, co-activation)
+- **Tracks** decisions, handoffs, and session history across conversations
+- **Traverses** causal and semantic graphs to answer "why" and "what led to" questions
+
+## Architecture
+
+```
+ Agent (Claude Code / OpenClaw / any MCP client)
+   │
+   ├── Hooks (automatic, ~90% of retrieval)
+   │   ├── context-surfacing    → injects <vault-context> on every prompt
+   │   ├── decision-extractor   → extracts observations after each response
+   │   ├── handoff-generator    → summarizes sessions for continuity
+   │   ├── feedback-loop        → reinforces referenced memories
+   │   ├── precompact-extract   → preserves state before context compaction
+   │   ├── curator-nudge        → surfaces maintenance suggestions
+   │   └── postcompact-inject   → re-injects authoritative context after compaction
+   │
+   ├── MCP Tools (agent-initiated, ~10%)
+   │   ├── memory_retrieve      → auto-routing entry point
+   │   ├── query / search / vsearch / intent_search / query_plan
+   │   ├── get / multi_get / find_similar / find_causal_links / timeline
+   │   ├── memory_pin / memory_snooze / memory_forget
+   │   └── lifecycle / vault / maintenance tools
+   │
+   └── REST API (optional, for non-MCP clients)
+       ├── POST /retrieve       → mirrors memory_retrieve
+       ├── POST /search         → direct mode selection
+       └── GET/POST endpoints   → documents, lifecycle, graphs
+
+   │
+   ▼
+ SQLite Vault (WAL mode)
+   ├── documents + content (FTS5 index)
+   ├── vectors (vec0 extension)
+   ├── memory_relations (causal, semantic, temporal, supporting edges)
+   ├── sessions + usage tracking
+   └── hook_dedupe (heartbeat suppression)
+
+   │
+   ▼
+ GPU Services (llama-server)
+   ├── :8088 — Embedding (EmbeddingGemma-300M default, zembed-1 SOTA upgrade)
+   ├── :8089 — LLM (qmd-query-expansion-1.7B)
+   └── :8090 — Reranker (qwen3-reranker-0.6B default, zerank-2 seq-cls sidecar SOTA upgrade)
+```
+
+## Key design principles
+
+1. **Local-first** — all data stays on your machine in a single SQLite file. No cloud dependencies unless you opt into cloud embedding.
+2. **Fail-open** — every hook and search path degrades gracefully. A failed GPU call returns BM25-only results, not an error.
+3. **Dual-mode** — the same vault is shared between Claude Code hooks and OpenClaw's memory plugin. Both runtimes read and write the same memory.
+4. **Progressive disclosure** — agents see compact results first (`compact=true`), then fetch full content only when needed. Minimizes context window usage.
+5. **Zero-config default** — a single vault with `clawmem bootstrap` gets you running. Multi-vault, cloud embedding, and profiles are opt-in.
+
+## Building a rich context field
+
+A filesystem-based context engine is only as useful as what you put into the filesystem. If your vault contains a handful of sparse memory files, the retrieval pipeline has little to work with — BM25 won't find relevant terms, vector search has few neighbors to compare, and graph traversal has no edges to follow.
+
+The agents that get the most from ClawMem are the ones with rich, diverse collections. Index broadly:
+
+| Content type | Example | Why it helps |
+|-------------|---------|-------------|
+| Memory files | `MEMORY.md`, session logs | Captures what happened and what was decided |
+| Research outputs | Analysis notes, comparison docs | Gives the agent domain knowledge it would otherwise lack |
+| Decision records | Architecture decisions, tradeoffs | Lets the agent understand *why*, not just *what* |
+| Learnings and antipatterns | Post-mortems, things to avoid | Prevents repeated mistakes across sessions |
+| Domain expertise | Reference docs, runbooks, SOPs | Provides stable context that rarely changes |
+| Project notes | Status updates, meeting notes, specs | Keeps the agent current on project state |
+
+A practical starting point: configure each project collection to index every `.md` file in the project (`pattern: "**/*.md"`). The composite scoring system handles the rest — decisions and hubs never decay, progress notes fade after 45 days, and the quality multiplier rewards well-structured documents over flat text dumps.
+
+### Document structure matters
+
+How you write documents affects how well they score. The [quality multiplier](concepts/composite-scoring.md#quality-multiplier-07---13) ranges from 0.7x (penalty) to 1.3x (boost) based on headings, lists, decision keywords, and frontmatter. Five well-structured decision documents with clear headings will consistently outscore fifty single-paragraph notes.
+
+### Keep code out of the vault
+
+ClawMem indexes prose, not code. Source files (`.ts`, `.py`, `.go`, etc.) are excluded by design — BM25 and vector models trained on natural language perform poorly on code syntax, and code retrieval needs AST-aware, symbol-level tools (call graphs, definitions, references). Document your technical decisions and architecture in markdown. Let the code live in version control and use a dedicated code search tool for code retrieval.
+
+## Integrations
+
+| Runtime | Integration | How | Services needed |
+|---------|------------|-----|-----------------|
+| Claude Code | Hooks + MCP stdio | `clawmem setup hooks` + `clawmem setup mcp` | watcher + embed timer |
+| OpenClaw | Memory plugin + REST API | `clawmem setup openclaw` (requires OpenClaw v2026.4.11+) | watcher + embed timer + `clawmem serve` |
+| Any MCP client | MCP stdio | Add to MCP config | watcher + embed timer |
+| Web / scripts | REST API | `clawmem serve` | watcher + embed timer + `clawmem serve` |
+
+All integrations share the same SQLite vault. The [watcher](guides/systemd-services.md#watcher-service) keeps the index fresh, the [embed timer](guides/systemd-services.md#embed-timer) maintains vector embeddings, and the [REST API](reference/rest-api.md) serves OpenClaw agent tools. GPU servers are optional — `node-llama-cpp` provides in-process fallback (Metal on Apple Silicon, Vulkan where available, CPU as last resort). Fast with GPU acceleration; significantly slower on CPU-only. The [curator agent](../agents/clawmem-curator.md) handles periodic maintenance on demand.
+
+## Next steps
+
+- [Quickstart](quickstart.md) — install and bootstrap in 5 minutes
+- [Concepts](concepts/architecture.md) — understand vaults, collections, and scoring
+- [MCP Tools Reference](reference/mcp-tools.md) — full tool reference with examples