Skip to main content

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

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)

Source distribution for blaxx-memory 0.1.0
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)

Table of built distributions (wheels) for blaxx-memory 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page