blaxx-memory 0.1.0

A self-updating AI memory layer for Claude Code: knowledge-graph engine + Obsidian vault, with per-session knowledge injection and skill/MCP usage tracking.

blaxx-memory

A self-updating AI memory layer for Claude Code. It turns a folder of knowledge (your skills + notes) into a knowledge graph, renders it as an Obsidian vault, injects the right knowledge into each Claude Code session, and tracks which skills & MCP servers actually get used — feeding that usage back into the graph.

 knowledge ──► injected per session ──► usage observed via hooks ──► fed back ──► knowledge
  (graph +        (SessionStart map +        (PostToolUse on             (sync /
   vault)         UserPromptSubmit)           Skill & mcp__*)             rollup)

graphify and Obsidian are not merged libraries. graphify is a graph-builder; an Obsidian vault is just a folder of .md files with [[wikilinks]]. This tool is the thin layer in the middle: it builds the graph itself (its own engine), writes the vault, and wires Claude Code's hooks + MCP.

Install

pipx install blaxx-memory          # recommended (isolated, on PATH)
uv tool install blaxx-memory       # if you use uv
pip install blaxx-memory           # into a virtualenv

Then wire it into Claude Code and pull the curated knowledge base in one step:

blaxx-memory install               # fetch the latest KB release -> ~/.blaxx, build, wire hooks + MCP

Keep it current with blaxx-memory self-update; diagnose with blaxx-memory doctor.

From source (uv; lockfile committed, hatchling backend):

uv sync                # .venv from uv.lock (core + dev + official MCP SDK)
uv sync --extra leiden # + Leiden clustering (else networkx Louvain fallback)
uv run pytest

Two tiers

• Central tier — your skill packs, copied into a stable ~/.blaxx and injected into every project. This is what "recall the NestJS/React conventions" reads from.
• Project tier — a lightweight map of the current project's own code, docs, and decisions (<project>/.blaxx/project-graph.json), built by /blaxx-memory / blaxx-memory map.

Recall merges both: a query searches the central skills and this project's code together.

Quickstart (two commands)

pipx install blaxx-memory
blaxx-memory install                 # fetch the curated KB + wire Claude Code

install downloads the latest knowledge-base release into the stable ~/.blaxx, builds it, installs the /blaxx-memory command, and auto-registers the MCP server — all pointing at ~/.blaxx, so recall works in every project. It refuses to wire an empty KB. Bring your own skills instead with --kb local:/path/to/skills (or --from /path/to/skills).

Inside Claude Code:

• /blaxx-memory how do I structure a nest module → recalls central skills and this project's code
• /blaxx-memory (no args) → maps THIS project (its code, docs, decisions) into the KB

Diagnose anytime with blaxx-memory doctor. Preview with --dry-run. Reverse with blaxx-memory uninstall. The MCP server is registered via the claude CLI (mcp add-json), falling back to a backed-up edit of ~/.claude.json if the CLI isn't on PATH.

How it works

Injection (hooks). init installs three hooks (commands carry --home <kb> so they find your knowledge base from any project):

Hook	Fires	Injects
SessionStart	session start/resume/clear	a compact map (clusters, god nodes, most-used)
UserPromptSubmit	every prompt	the top-k relevant skills/notes for that prompt
PostToolUse (Skill|mcp__.*)	after a Skill/MCP call	nothing — it logs usage

Hooks fail open: any error prints nothing and exits 0, so they can never break a session.

Retrieval. Dependency-free BM25 over the prebuilt graph.json (name + description + summary + tags), with stopword removal, a domain/name-match boost, and small usage/PageRank boosts. Fast enough for the per-prompt hook.

Usage tracking & privacy. Each Skill/MCP call is appended to .blaxx/usage.jsonl (kind, name, server, project, session). build/sync folds counts onto nodes and the wiki/_usage.md dashboard. Opt out with track_usage = false; exclude projects with ignore_projects = [...].

MCP server. blaxx-memory mcp (stdio) exposes query_knowledge(query, k), get_skill(name), record_decision(note, links), record_learning(title, learning, …) (schema-correct write-back into <project>/.blaxx/learnings/), ask_with_memory(question, k) (below), and a graph://summary resource — the portability layer for other MCP-capable assistants and the on-demand "fetch territory" half of the design.

LLM harness (ask_with_memory). The ask_with_memory(question, k) MCP tool makes any model answer through the memory — no separate CLI. It runs inside the server and reads the graph directly: project CLAUDE.md + the knowledge map as the system prompt, the top-k relevant skills injected into the question, then one completion (injection-only). Two adapters cover essentially every model: Anthropic Messages and OpenAI-compatible Chat Completions (OpenAI, Ollama, OpenRouter, Groq, vLLM via base_url). Stdlib HTTP only; API keys come only from env vars (config stores the var name). It is gated: with no harness config / API key it returns a setup hint, so the recall/record tools stay usable. Configure it under [tool.blaxx-memory.harness] (below) and call it from any MCP client.

Commands

Command	Does
install	one-shot: fetch/copy skills → ~/.blaxx, build, wire hooks + /blaxx-memory + auto-MCP (--kb latest|local:<path>|gh:<tag>, --from, --scope, --dry-run)
scaffold	create an empty raw/ (+ a short README) to start your own skills (bring-your-own)
self-update	upgrade the engine (pipx/uv/pip) + refresh the KB + rebuild + re-wire (--check, --tool-only, --kb-only, --pre)
map	map THIS project's code/docs/decisions → <project>/.blaxx/project-graph.json
doctor	diagnose recall: central KB nodes, project map, MCP, hooks
uninstall	reverse install (hooks, command, MCP server, CLAUDE.md pointer)
build	ingest sources → graph.json (+graph.html) + Obsidian vault
sync	rebuild the central KB, folding in newly-recorded usage
stats	summarize the current graph
init	lower-level wiring only (no build / no auto-MCP) — prefer install
hook <event>	hook entry point (called by Claude Code)
mcp	run the MCP knowledge server (stdio) — exposes the 5 tools incl. ask_with_memory

Configure

Defaults: sources ./raw, vault ./wiki, graph ./output, home ./.blaxx. Override via a [tool.blaxx-memory] table in blaxx-memory.toml or pyproject.toml:

[tool.blaxx-memory]
sources = ["raw", "notes"]
track_usage = true
ignore_projects = ["secret-client-x"]

[tool.blaxx-memory.harness]          # for the `ask_with_memory` MCP tool
provider = "anthropic"               # or "openai" (any OpenAI-compatible endpoint)
model = "claude-opus-4-8"            # REQUIRED for provider = "openai"
base_url = ""                        # e.g. "http://localhost:11434/v1" for Ollama
api_key_env = "ANTHROPIC_API_KEY"    # NAME of the env var; "" = keyless local. Never the key itself.
k = 4                                # knowledge hits injected into the question
# temperature is omitted unless set (Claude Opus 4.7+ rejects it)

The harness table is read from the project root first, then the central ~/.blaxx; CLI flags override both.

Status

Phase	What	State
P0/P1	engine: ingest → graph.json + Obsidian vault	✅
P2	injection hooks (SessionStart map + UserPromptSubmit retrieval)	✅
P3	usage tracking (PostToolUse + rollup, privacy opt-out)	✅
P4	FastMCP knowledge server + bundled skill	✅
P5	productize: idempotent init/uninstall, packaging, docs	✅
P6	graphify-style one-command install + /blaxx-memory command + auto-MCP	✅
P7	two-tier KB: stable ~/.blaxx central + per-project map (codemap) + merged recall + doctor	✅
P8	LLM harness: chat REPL/one-shot, any model follows the memory via MCP (tool loop + injection, Anthropic + OpenAI-compatible adapters)	✅
later	publish to PyPI · SSE streaming for chat · external MCP servers in the harness · tree-sitter/graphify-import for richer code graphs · Claude Code plugin packaging	⏳

Develop

uv sync --extra mcp     # create/refresh .venv from uv.lock (dev group included)
uv run pytest           # ingest, graph/pagerank, retrieval, usage, mcp, install, harness
uv lock                 # re-lock after changing dependencies