homestead-memory

# homestead-memory

<!-- mcp-name: io.github.fuckbigtech-ai/homestead-memory -->

[![PyPI](https://img.shields.io/pypi/v/homestead-memory)](https://pypi.org/project/homestead-memory/)
[![CI](https://github.com/fuckbigtech-ai/homestead-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/fuckbigtech-ai/homestead-memory/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/homestead-memory)](https://pypi.org/project/homestead-memory/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Stop renting your mind.**

Local-first, verifiable AI memory. Your notes stay plain markdown you can read,
`git diff`, and own, and the memory **catches its own rot, tampering, and poisoning.**

Every other memory layer asks you to *hope* it remembers. This one lets you
*watch it catch the rot, live:*

![hsm verify --demo: a clean vault scores MEMORY INTACT 100/100, then rot is planted and caught live: ROT DETECTED 0/100 with every finding named](docs/demo.gif)

```bash
pip install homestead-memory      # Python 3.10+, macOS / Linux / Windows, zero deps
npm install -g @tobilu/qmd@2.1.0 # optional hybrid retrieval runtime

hsm verify --demo
# ① a clean vault           ✅  MEMORY INTACT — 100/100
# ② rot is planted…         🔴  ROT DETECTED —   0/100
#    🔴 [self_contradiction] the note argues with itself about its own status
#    🔴 [uncited_claim]      a distilled claim has no source citation
#    🔴 [dangling_citation]  a cited source no longer exists
#    ⚠️  [broken_link]        a reference points at a note that isn't there
```

> **Got `No matching distribution found`?** macOS still ships Python 3.9 as its built-in
> `python3`, and this needs 3.10+. Nothing is wrong with the package. Either use a newer
> Python, or skip installing entirely:
> `uvx --from homestead-memory hsm verify --demo`
> ([uv](https://docs.astral.sh/uv/) fetches a suitable Python for you.)

`hsm verify` exits non-zero on rot — it gates CI and cron like a test suite.

## What did your agent actually do?

Agents fail quietly. The run reports success, the tool returns 200, and the thing you
asked for did not happen. There is usually no record to contradict it.

```bash
hsm hook --install     # prints a Claude Code hook; you paste it, nothing is edited for you
hsm watch              # what your agent did, in order

#     0  14:02:11  Bash           npm test
#     1  14:02:19  Read           src/api/billing.py
#     2  14:02:24  Edit           src/api/billing.py
```

Every entry is hash-chained to the one before it, so editing, deleting, or reordering
any record breaks every hash after it. `hsm verify` reports the break at the exact
index. Sign it and a wholly rebuilt chain is caught too.

**This is a file, not a platform.** Agent observability tools are far richer than this
and they want a deployment: the self-hosted ones document a production floor of several
services and roughly 16 GB of RAM. This is `pip install`, one hook line, and a JSONL
file on your disk. Different job. If you need dashboards, evals, and span analytics,
use one of those. If you want a record you can grep and prove, use this.

Secret-shaped values are redacted and payloads truncated to a 200-character head, with
a SHA-256 of the full original kept so the evidence survives redaction. That is a
mitigation, not a guarantee: no pattern list is complete.

```bash
hsm export --evidence  # a pack anyone can verify with no install at all
```

The pack carries the records, the signature, the public key, an integrity report, and a
standard-library verifier a third party can read in full and run. It states what it does
NOT prove, including that a signature only establishes origin if you already know which
key to expect.

**Capture is Claude Code only right now.** The MCP integration below works anywhere MCP
does; the hook that records *every* tool call uses a Claude Code `PostToolUse` hook.
Cursor and Codex need their own mechanisms and those are not built yet.

## Quickstart (60 seconds)

```bash
hsm init   ./my-vault          # scaffold or adopt any markdown folder
hsm ingest ./my-vault          # index it (hybrid BM25+vector via qmd, optional)
hsm ask    "what did I decide about X?"
hsm ask    "what did I decide about X?" ./my-vault --budget 1200 --json
hsm search "what did I decide?" ./my-vault --retrieval balanced --json
hsm qmd start                  # persistent loopback runtime; no shared global index
hsm verify ./my-vault          # the integrity gate — the whole point
hsm distill ./my-vault         # optional: build the cited, verifiable fact layer
hsm history <note> --as-of 2026-06-01   # what was true THEN (temporal layer)
hsm serve                      # local HTTP API (auth'd, loopback-only)
```

Python agents can use the SDK directly:

```python
from homestead_memory import connect

memory = connect("~/my-vault", agent="my-agent")
memory.remember("user", "city", "Berlin")
memory.ask("what city is the user in?")
```

The local HTTP API is documented in [`docs/openapi.yaml`](docs/openapi.yaml).

### Retrieval profiles

Homestead keeps qmd in dedicated cache and config directories. It never runs
maintenance against qmd's global index. Every structured result reports `engine`,
`retrieval_mode`, `degraded`, `reason`, `elapsed_ms`, and `index_age_seconds`.

| profile | behavior | use |
|---|---|---|
| `fast` | BM25 only | exact names, paths, and low-latency probes |
| `balanced` | lexical + vector, no LLM reranker | hooks and normal agent context |
| `quality` | lexical + vector + reranker | explicit high-value research queries |

The route is persistent qmd MCP, then the dedicated qmd CLI, then a read-only
direct scan. Run `hsm qmd doctor`, `hsm qmd refresh`, and `hsm qmd status` to inspect
the runtime without touching any other qmd collection.

Refresh is explicit and incremental. It writes an atomic checkpoint beneath
`.hsm/refresh-state.json`, refuses foreign or unhealthy QMD runtimes, emits a
live heartbeat while QMD works, and commits the vault fingerprint only after
embedding reaches zero pending vectors. Reads never trigger an implicit
refresh; if QMD is unavailable, retrieval falls back to a read-only scan and
reports the degraded engine and reason.

For a Linux/systemd reference deployment, see `deploy/reference/`.

## Memory under the router

Routers can swap the served model while homestead-memory keeps the same vault
underneath. The model name is just the runtime argument; provenance is stamped as
`name@model` in the `agent` field when a write happens.

```python
from homestead_memory import connect
from homestead_memory.adapters.openai_compat import MemoryChat

memory = connect("~/my-vault")

def remember_reply(response, memory, agent):
    memory.remember(
        "conversation",
        "last_reply",
        response.choices[0].message.content,
        source="chat",
        agent=agent,
    )

chat = MemoryChat(openai_compatible_client, memory, remember_fn=remember_reply)
chat.create(model="claude-sonnet-4.7", messages=[{"role": "user", "content": "brief me"}])
chat.create(model="glm-4.7", messages=[{"role": "user", "content": "continue"}])

memory.history("conversation")  # agents include assistant@claude-sonnet-4.7 and assistant@glm-4.7
```

LiteLLM can use the same pattern with a pre-call injection helper and a success
logger:

```python
from homestead_memory import connect
from homestead_memory.adapters.litellm_memory import MemoryLogger, inject_memory

memory = connect("~/my-vault")
messages = inject_memory([{"role": "user", "content": "brief me"}], memory)

# LiteLLM callback registration style depends on your app setup.
logger = MemoryLogger(memory, agent_name="assistant")
```

MCP already sits above harness-level routers. In a `claude-code-router`-style
setup that swaps the backend model, homestead-memory keeps working with
zero config because memory is external to the model. `history()` and `verify`
then attribute every recorded fact to the exact `name@model` that wrote it.

## Integrations

Adapters target the public framework interfaces listed here as of the current
releases and may need version bumps as those APIs evolve. Core remains
stdlib-only; install only the extra for the framework you use.

Universal tools work with any orchestrator that can register callables or
JSON-schema function tools:

```python
from homestead_memory import connect
from homestead_memory.adapters.tools import recall_tool, remember_tool, tool_specs, verify_tool

memory = connect("~/my-vault", agent="my-agent")
tools = [remember_tool(memory), recall_tool(memory), verify_tool(memory)]
specs = tool_specs(memory)  # name, description, parameters
```

LangGraph `BaseStore` (targets `langgraph>=0.2`):

```python
from homestead_memory import connect
from homestead_memory.adapters.langgraph_store import HomesteadStore

store = HomesteadStore(connect("~/my-vault", agent="langgraph"))
graph = builder.compile(checkpointer=checkpointer, store=store)
```

CrewAI storage/memory (targets `crewai>=0.70`, storage-style
`save/search/reset`):

```python
from homestead_memory import connect
from homestead_memory.adapters.crewai_memory import HomesteadCrewAIStorage

storage = HomesteadCrewAIStorage(connect("~/my-vault", agent="crewai"))
storage.save("Researcher found the supplier shortlist", metadata={"task": "supplier_shortlist"})
```

AutoGen `autogen_core` Memory protocol (targets `autogen-core>=0.4`):

```python
from autogen_core.memory import MemoryContent, MemoryMimeType
from homestead_memory import connect
from homestead_memory.adapters.autogen_memory import HomesteadAutoGenMemory

memory = HomesteadAutoGenMemory(connect("~/my-vault", agent="autogen"))
await memory.add(MemoryContent(content="Use metric units", mime_type=MemoryMimeType.TEXT))
```

OpenAI Agents SDK Session protocol or function tools (targets
`openai-agents>=0.0.1`):

```python
from homestead_memory import connect
from homestead_memory.adapters.openai_agents import Homest