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
.mdfiles 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
~/.blaxxand 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
Metadata
Release files for blaxx-memory 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| blaxx_memory-0.1.0.tar.gz | 131.8 kB | With provenance | Details for blaxx_memory-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| blaxx_memory-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for blaxx_memory-0.1.0-py3-none-any.whl |
Total release size: 190.3 kB
Release files / blaxx_memory-0.1.0.tar.gz
| Download URL | blaxx_memory-0.1.0.tar.gz |
|---|---|
| Size | 131.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
88a38ec1ccd39def08dc4660cca06d5f4127cd669ff676747c796470e96346e3
|
|
BLAKE2b-256 checksum How to use checksums |
ac944eced860ede810df22536139f6e0aa3cfea02ec90da1e88cb781aa821465
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.
Transparency logRelease files / blaxx_memory-0.1.0-py3-none-any.whl
| Download URL | blaxx_memory-0.1.0-py3-none-any.whl |
|---|---|
| Size | 58.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5977f49f619355a3368278e6c7e172f2998b260ff4cc75405d71d3bbf3ff09b7
|
|
BLAKE2b-256 checksum How to use checksums |
0c83cb781af3f330b3f98a769a208566f808974d0e99a9b98bf0528a755e8d20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.
Transparency logSecurity for blaxx-memory 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for blaxx_memory-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.