Metadata-Version: 2.4
Name: blaxx-memory
Version: 0.1.0
Summary: A self-updating AI memory layer for Claude Code: knowledge-graph engine + Obsidian vault, with per-session knowledge injection and skill/MCP usage tracking.
Project-URL: Homepage, https://github.com/Dineshs737/blaxx-memory
Project-URL: Repository, https://github.com/Dineshs737/blaxx-memory
Project-URL: Issues, https://github.com/Dineshs737/blaxx-memory/issues
Author: blaxx
License: MIT
Keywords: ai-memory,claude-code,knowledge-graph,mcp,obsidian,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Requires-Dist: networkx>=3.2
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: leiden
Requires-Dist: igraph>=0.11; extra == 'leiden'
Requires-Dist: leidenalg>=0.10; extra == 'leiden'
Provides-Extra: mcp
Description-Content-Type: text/markdown

# 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

```bash
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:

```bash
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):

```bash
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)

```bash
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`:

```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

```bash
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
```
