Documentation

MCP Server setup, the 12 ENGRAM tools, and a tour of your Settings panel.

1. MCP Server

ENGRAM exposes an MCP (Model Context Protocol) server so your local agents — Claude Code, Claude Desktop, or any other MCP-compatible client — can read, search, and write articles in your knowledge base. The same tools also drive coding-session ingest, external-conversation capture, and the Knowledge Gaps closure loop.

The ENGRAM MCP server lives at https://engram.pvelua.net/mcp/ (the trailing slash is required). It authenticates per-user via a Personal Access Token (PAT) you mint from your Settings panel.

1.1 Configuration

Step 1 · Mint a PAT

Sign in to ENGRAM, click your avatar (top-right), open Settings → API Keys, and click + Create Key. Give it a memorable name (e.g. "Claude Code on MacBook") and copy the engram_pat_… token immediately — the raw key is shown only once. If you lose it, just create a new one and revoke the old.

See §2.2 API Keys for the full panel walkthrough.

Step 2 · Claude Code

Claude Code speaks MCP over HTTP natively — no wrapper needed. Run this once from any terminal (the -s user flag scopes the registration globally so it works from any project):

claude mcp add -s user --transport http engram-kb \
  https://engram.pvelua.net/mcp/ \
  --header "Authorization: Bearer engram_pat_your_token_here"

Verify with claude mcp list — the engram-kb entry should report ✓ Connected. Restart any open Claude Code session for the new server to load.

Tip. If you'd rather keep the raw PAT out of ~/.claude.json, export it as a shell env var first (export ENGRAM_PAT=engram_pat_…), then reference it in the header. Note that claude mcp add resolves env vars at registration time and bakes the literal value into the config — for true "no plaintext at rest", scope the registration to a project (-s project) and gitignore the resulting .mcp.json.

Step 3 · Claude Desktop

Claude Desktop's built-in MCP runtime is stdio-only for non-public servers, so we use mcp-remote — a small npm package that runs as a local stdio process and relays JSON-RPC to a remote HTTP MCP endpoint. Edit your claude_desktop_config.json (see paths below) and add this entry:

{
  "mcpServers": {
    "engram-kb": {
      "command": "/usr/local/bin/npx",
      "args": [
        "mcp-remote",
        "https://engram.pvelua.net/mcp/",
        "--header",
        "Authorization: Bearer ${ENGRAM_PAT}"
      ],
      "env": {
        "ENGRAM_PAT": "engram_pat_your_token_here"
      }
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing. The MCP indicator (Settings → Developer) should show engram-kb as connected.

Two gotchas. The trailing slash on /mcp/ is load-bearing (no slash → 307 redirect that the JSON-RPC client doesn't follow). And command needs an absolute path to npx — Claude Desktop launches with a stripped PATH so a bare npx won't resolve. which npx in your terminal tells you the right path (Homebrew installs put it at /usr/local/bin/npx on Intel Macs or /opt/homebrew/bin/npx on Apple Silicon).

1.2 MCP Tools

ENGRAM exposes 12 MCP tools across five capability groups. Each tool is callable by the agent as soon as the server is registered — you don't import or list them explicitly. Just describe the task in natural language ("save this draft to my KB", "find articles related to X") and the agent picks the right tool.

KB writes

sync_article

Create-or-update an article keyed on (repository, file_path). Idempotent — re-runs produce a superseding version, not a duplicate.

Use when: the article corresponds to a real on-disk file (the most common case is "mirror this file into the KB"). Re-running on the same path automatically versions the content.
Key params: title, content_markdown, repository, file_path.
Example: "Sync docs/architecture.md to my ENGRAM KB."

create_article

Create a new article unconditionally — no identity dedup. Use when the content has no clear file backing (chat-drafted output, web research summaries).

Use when: you don't plan to iterate on the article locally — one-off captures, comparison reports, web summaries.
Key params: title, content_markdown, optional source_agent, tags, reason.
Example: "Draft a comparison of vector databases and save it as a new ENGRAM article."

KB reads

search_articles

Title-keyword search. Multi-word queries are AND'd against titles (case-insensitive). Ranked exact > starts-with > all-tokens-present.

Use when: you know roughly what the article is called. Results include a short excerpt for disambiguation.
Key params: query, limit (default 10).
Example: "Search my KB for articles about authentication."

find_related_articles

PPR-based topic and entity discovery. Returns articles ranked by graph proximity to the query's entities, not title overlap.

Use when: title search would be too narrow — you want a comparison set, or everything that mentions a concept.
Key params: query, limit (default 10).
Example: "Find ENGRAM articles related to vector database comparisons."

get_article

Fetch full markdown content and version-chain metadata for a single article by ID.

Use when: you've narrowed down via search/find/list and want the full body. The response includes version and is_latest so the agent knows whether it's reading current content.
Key params: article_id.

list_articles

Recent articles inventory (latest-of-chain only). Supports creation_trigger, since, and tag filters.

Use when: browsing — "what did I article last week?", "all my MCP-created articles", "everything tagged with foo".
Key params: limit, optional creation_trigger, since, tag.

Code sessions

ingest_code_session

Persist a Claude Code session (the JSONL transcript) into the graph as :CodeSession + :CodeRecap + :CodeAction nodes.

Use when: you want a past coding session retrievable later by topic ("what did I do about Neo4j ownership last week?"). Re-runs are MERGE-safe — idempotent.
Key params: session_id (the JSONL filename UUID; the server finds it under ~/.claude/projects/).
Note: requires the operator to enable code-session ingest globally.

find_related_code_sessions

PPR-based code-session discovery — sibling to find_related_articles but over your coding history.

Use when: recalling what you did before (file edits, decisions, prior context) — distinct from "what I researched", which is find_related_articles.
Key params: query, limit (default 10).
Example: "What did I do about Neo4j connection pooling in past sessions?"

External conversations

record_external_conversation

Capture a chat you had on another LLM host (ChatGPT, Gemini, Claude AI Chat, …) so its entities flow into ENGRAM's memory-biased retrieval.

Use when: you've been researching something on a non-ENGRAM chat surface and want that work to inform future ENGRAM retrievals — and especially before turning the research into an article.
Key params: summary, source_agent, external_project, conversation_ref, optional related_repo, tags.
Pattern: call this first to register the external conversation, then pass the same (source_agent, external_project, conversation_ref) tuple as source_conversation_ref on a subsequent create_article/sync_article call for end-to-end provenance.

Knowledge Gaps

list_kb_gaps

Browse the inventory of detected knowledge gaps (:GapItem nodes) — topics where the KB has thin coverage or known retrieval failures.

Use when: you want to see what the gap-analysis detectors have flagged for follow-up.
Key params: optional type, severity, status, limit.

propose_gap_closure

Draft a closure proposal against a specific gap — the primary submission surface for autonomous closure loops (Cowork, etc.).

Use when: you (or an autonomous agent) have a candidate fix for a gap and want it queued for review before execution.
Key params: item_id, action_type, plus context fields like proposed_title, draft_excerpt, draft_markdown.

execute_gap_closure

Execute an already-approved gap proposal — write the article, MERGE the alias, or whatever the proposal's action_type specifies.

Use when: a previously-proposed closure has been approved (manually or via policy) and you want to materialise it.
Key params: proposal_id.

2. Settings

Your Settings panel is where you manage your account, mint PATs for MCP clients, and label the machines that have ingested your Claude Code sessions. Open it from the avatar menu (top-right of the app) — it appears as a drawer with three tabs.

2.1 Profile

Settings → Profile · personal info + LLM connection.

Personal Information — first name, last name, email. Used by the app for greetings and for the audit log when you take admin actions.

LLM Settings — your "bring-your-own-LLM" configuration. ENGRAM uses your provider + model + API key for response generation and article authoring; everything else (entity extraction, summarisation, community labels) runs on the operator's Anthropic budget by design.

Provider: Anthropic, Google, or OpenAI.
Model: picked from the provider's catalogue (e.g. claude-sonnet-4-6, gemini-2.5-pro, gpt-5).
API key: stored masked; only the last few characters are shown back to you. The green Connected indicator means ENGRAM has successfully reached your provider with the key.

2.2 API Keys

API Keys tab showing four active Personal Access Tokens with names like 'Claude Desktop', 'Claude Code', creation dates, last-used dates, and Revoke/Delete buttons — Settings → API Keys · per-tool PATs with revoke and delete controls.

Personal Access Tokens (PATs) let external agents — Claude Code, Claude Desktop, and the engram-watcher CLI — call ENGRAM on your behalf. Each token authenticates as you: anything it does shows up in your audit history.

Create a PAT

Click + Create Key, give it a name that identifies where you'll use it (e.g. "Claude Code — MacBook", "Claude Desktop — Work"), and confirm. ENGRAM shows the full engram_pat_… token once.

Copy it immediately. The raw token is hashed and stored — ENGRAM cannot recover it later. If you misplace one, create a new key and delete the lost one. The displayed list shows only the first few + last few characters (e.g. engram_pat_rjkcy…2wCM) for identification.

Revoke vs Delete

Revoke: immediately invalidates the token — any further request returns 401. The row stays in the list (now marked Revoked) so the audit history retains the name and creation context. Use this when you suspect a token has leaked or you're rotating credentials.
Delete: removes the row entirely. Equivalent to "revoke + forget" — pick this once you're sure you'll never need the row for forensic context. Already-revoked tokens are also safe to delete.

Each row shows Created and Last used dates — useful for spotting tokens that haven't been touched in a while (candidates for cleanup) or, conversely, tokens that are seeing unexpected traffic.

2.3 Hosts

Hosts tab showing two machines: an unlabeled host with auto-detected hostname 'Mac.attlocal.net', and 'Work MacBook Pro 14' labeled host with hostname 'MacBook-Pro14.local', each showing session counts and first/last-seen dates — Settings → Hosts · machines that have ingested code sessions, with optional friendly labels.

The Hosts tab lists every machine that has uploaded a Claude Code session to your KB via the engram-watcher CLI. Each row is auto-created the first time a host posts a session — the hostname comes from socket.gethostname() on the sending machine.

Label — click on a host's name to give it a friendlier display name (e.g. "Work MacBook Pro 14" for MacBook-Pro14.local). The label is used everywhere the host appears in the UI: the Coding Sessions panel, the Project insights, and host-grouped filters. The raw hostname stays as the system-level identifier.

Sessions / First seen / Last seen — counters and timestamps maintained by the ingest pipeline. Useful for spotting hosts that have gone quiet (laptop in storage, watcher daemon stopped) or for confirming a freshly installed watcher is talking to ENGRAM.

Don't see a host you expect? Only machines running the engram-watcher CLI produce Hosts rows. If you've registered a PAT but haven't installed the watcher yet, this tab stays empty — that's expected.