hifz

hifz gives a coding agent a memory that persists across sessions. One Axum process owns an embedded SurrealDB, a local ONNX embedder, a hybrid search index, a typed knowledge graph, code intelligence, the REST API, an MCP server, and a dashboard. Anything that speaks HTTP is a client. Nothing leaves your machine — embeddings run locally and LLM features are opt-in via Ollama.

It captures your work as observations, sessions, and runs; distills the durable parts into curated memories; recalls them with hybrid search and 1-hop graph expansion; grounds them in your git history; and links them straight to the lines of code they describe.

Save a lesson, decision, bug, fix, plan, or design once — recall it in any future session. The browser lets you search, filter by category, sort by strength × access, and expand any memory to its full content, tags, and the files it touches.

# save (CLI — POSTs straight to the server, no agent needed)
hifz save --content "JWT refresh tokens live in Redis, not the JWT claims" \
  --title "Auth refresh design" --category lesson --project hifz --file src/auth/session.rs

# recall (MCP) — hybrid search + 1-hop graph expansion
hifz_recall { "project": "hifz", "query": "how does refresh work?" }

Each memory carries a strength, an access count, and a last_committed_at watermark. Retrieval ranks by a blend of relevance, recency decay, reinforcement, and grounding — so what you actually shipped surfaces first and abandoned notes fade.

hifz doesn't store memories as a flat list. Observations (captured tool use), sessions, runs, commits, and curated memories are all typed nodes joined by typed edges — provenance, conceptual, argumentative, lifecycle, and code-domain. The graph view renders the whole substrate: shapes encode node kind (hexagon = memory, diamond = run, ellipse = observation, rounded rect = session, tag = commit), colors encode type, and edge color/style encodes the relation.

Recall pulls 1-hop neighbors from this graph, so a memory that doesn't match your query directly but is linked to a hit can still surface. Edges are created deterministically on write (embedding KNN, shared concepts, shared files) and optionally enriched by an LLM. Full vocabulary and type-pair rules: docs/ontology.md.

hifz indexes your repository with tree-sitter (Rust, Python, JavaScript/TypeScript, Go, Java, C, C++), chunks it language-aware, embeds every chunk, and extracts a symbol manifest. Search is hybrid — an identifier-aware BM25 index fused with vector KNN — and memories can be linked to a precise file + line range or to a named symbol. The /code page searches it directly; hits are located previews (file · line range · highlighted snippet) you can copy or open.

# index a repo, then search it
hifz_code_index  { "project": "hifz", "root": "/path/to/repo" }
hifz_code_search { "project": "hifz", "query": "session refresh token", "language": "rust" }

Code lives in dedicated tables (code_chunk, code_symbol), so this search is always code — scoped by project, with optional language/path filters. A repo is parsed once: this index is the single source of truth, and Maktab builds its corpus graph by projecting from it (no second parse). Memory→code edges record the original (path, start, end) and re-anchor on re-index: when a file is re-split, the edge follows the lines it pointed at, or is dropped if those lines were deleted. Symbol links survive chunk re-splitting entirely. Indexing is idempotent (mtime + content hash), honors .gitignore, and reconciles deletions. Operator's guide: docs/code-indexing.md.

When a project mixes documents and code, Maktab search (the /ask page in Search mode) returns every kind together and you narrow with the type facet — Code_symbol, External, Document, Concept. Maktab's code_symbol nodes are projected from the same core index above; this is the corpus-wide view, where core code search is the precise, line-level one.

Maktab rides the same substrate to turn a codebase plus its docs into a clustered, queryable corpus graph. Point it at a repo path, a git URL, or upload files; then build runs a pipeline — ingest docs → project the code graph → extract concepts → cluster → insights.

Ask the corpus a question and get an answer grounded in citations — every claim links back to a source document, code symbol, or concept, with the openable URI and the matching passages.

maktab code   /path/to/repo      # project the code graph
maktab ingest /path/to/docs      # PDFs, markdown, txt
maktab extract                   # concept extraction (LLM)
maktab cluster                   # modularity clustering
maktab query  "how does recall rank results?"

Maktab is feature-gated — build with --features maktab to mount its routes under /api/v1/maktab.

• Plans are first-class memories (category='plan'). Activating one pins it and injects its title into the project's core context, so it rides along on every recall. Completing it clears the active tag but keeps it searchable as history.
• Sessions & runs capture the trajectory of work — observations grouped into task-scoped runs — without you doing anything; the Claude Code adapter posts them via hooks.
• Replay reconstructs the causal chain of a session as a transcript.
• Commit-grounding is the spine: when a commit lands, memories and code touching the committed files are strengthened and exempted from decay. Work that shipped persists; work that was abandoned fades. See plan-commit-grounding.md.

git clone https://github.com/arriqaaq/hifz.git
cd hifz
cargo build --release
./target/release/hifz serve --db-path ~/.hifz/data

Save and search over HTTP:

curl -X POST http://localhost:3111/api/v1/memories \
  -H 'content-type: application/json' \
  -d '{"project":"demo","title":"Auth uses JWT","content":"Sessions are signed JWTs in HttpOnly cookies."}'

curl -X POST http://localhost:3111/api/v1/search \
  -H 'content-type: application/json' \
  -d '{"project":"demo","query":"authentication"}'

Open http://localhost:3111 for the dashboard.

The plugin is a client of a running hifz server, so order matters:

1. Build the binary — cargo build --release (→ target/release/hifz).

2. Register the MCP server in .mcp.json at the project root. The command path must point at the binary you built (debug vs release must match):

{
  "mcpServers": {
    "hifz": { "command": "/absolute/path/to/target/release/hifz", "args": ["mcp"] }
  }
}

3. Start the server. On macOS, install it as an always-on service so the plugin never silently drops observations:

make install-service     # cargo build --release + load launchd agent
# ad-hoc alternative:
./target/release/hifz serve --db-path ~/.hifz/data

4. Install the plugin (hooks + skills):

claude plugin marketplace add /path/to/hifz/adapters/claude-code
claude plugin install hifz@hifz
claude plugin list                       # verify: hifz@hifz → enabled

5. Restart Claude Code. Hooks, skills, and the MCP server load at startup. After restart, /mcp lists hifz.

The adapter ships four skills — /recall, /remember, /forget, /session-history — plus lifecycle hooks that auto-capture tool use, prompts, and session/run boundaries. Relevant project memory auto-injects at session start — no configuration needed.

For non–Claude Code clients: anything that can POST /api/v1/memories and POST /api/v1/search is a first-class memory client; add POST /api/v1/agent/observe to populate the capture layer. See AGENTS.md.

make install-service     # cargo build --release, then load com.hifz.server
make service-status      # state/pid + /api/v1/livez check
make restart-service     # cargo build --release, then roll the new binary
make uninstall-service   # remove the agent (keeps ~/.hifz/data and logs)

Logs: ~/.hifz/logs/server.{out,err}.log. DB: ~/.hifz/data, port 3111.

• After changing hifz code, run make restart-service — the daemon runs a fixed target/release/hifz and won't pick up a rebuild until restarted.
• make dev is foreground/testing only and conflicts with the service on port 3111. Stop the service first, or run HIFZ_PORT=3120 make dev.
• make stop only pauses the daemon — KeepAlive resurrects it in ~10s. Use make uninstall-service to truly stop it.

A curated long-term layer sits above a dense, short-lived capture layer; consolidation lifts patterns from one into the other.

Write path. Every saved memory is embedded, stored, then linked against existing memories through three independent channels. Any channel over its threshold creates an edge:

Entity extraction (files, concepts, functions, identifiers) is deterministic. Evolution is opt-in: when enabled, an LLM reads up to five graph neighbors and may add tags, propose conceptual edges, or mark older memories superseded.

Read path. Hybrid retrieval (BM25 + HNSW) fused with reciprocal rank fusion, expanded one hop over the graph (neighbor score = seed × 0.5 × edge weight), then ordered by a Rust-side score:

score = strength × exp(-age_days / HALF_LIFE) × (1 + ACCESS_COEF × min(access, ACCESS_CAP))

Typed knowledge graph. Edges are typed and segmented by source so retrieval can weight them differently:

Every edge carries a reason field. Traverse from any seed with POST /trace (or hifz_trace).

Versioning. Memories are append-only. When something supersedes an older version, the older row stays — is_latest flips to false and the new ID is appended to supersedes[]. Every retrieval filters WHERE is_latest = true; the chain is kept for provenance and audit.

Full architecture, module index, and the observation pipeline: ARCHITECTURE.md.

hifz operates in one of two modes per insert. Both are valid; the difference is what the runtime can derive without an external service.

Same code path runs both ways. A row written in one mode reads fine in the other.

A per-project core_memory table sits above raw memory, and consolidation writes its output back into memory under two dedicated categories:

Consolidation is on-demand via POST /consolidate (Semantic · Reflect · Procedural · Decay). LLM tiers are skipped silently when Ollama is unavailable.

Embeddings use fastembed AllMiniLM-L6-V2 (384-dim ONNX, runs locally — no network). LLM features are opt-in via Ollama. Optional ~/.hifz/.env:

OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:4b
HIFZ_AUTO_COMPRESS=true     # richer observation summaries
HIFZ_LLM_EVOLVE=true        # post-save LLM refinement

./benchmark/download_dataset.sh
cargo run --bin longmemeval-bench -- bm25
cargo run --bin longmemeval-bench -- hybrid
cargo run --release --bin memory-bench -- full

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | /path/to/hifz mcp

• ARCHITECTURE.md — full architecture, write/read pipelines, consolidation, module index.
• AGENTS.md — building your own adapter / agent integration.
• docs/ontology.md — categories, edge vocabulary, type-pair rules, mode matrix.
• docs/code-indexing.md — code intelligence operator's guide.
• docs/architecture/memory.md — memory model deep dive.

Apache License 2.0