Skip to main content

lkhu — Like Human

Memory for Claude Code that works like a human brain: thoughts stored as latent vectors, not text. Zero LLM calls, zero API cost, fully local.

License: Apache 2.0 Python 3.11+ Version 0.1.0

Why lkhu

Most memory systems for coding agents store memories as natural language — summaries, observations, transcripts. That works, but it has a built-in tax: every save calls an LLM to compress text, and every recall pushes paragraphs back into the context window. The more you remember, the more tokens you burn re-reading your own past.

lkhu takes the human-brain route instead. You don't store your memories as essays — you store compressed traces and reconstruct words only when you need to speak. lkhu does the same: every memory becomes a "scent", a 1024-dimensional latent vector built with VSA/HRR (Vector Symbolic Architecture, Holographic Reduced Representations). Storage, association, consolidation, and forgetting are all pure vector math:

  • 0 LLM calls in the entire memory pipeline — save, recall, consolidate, decay, and cleanse use only a local embedding model plus numpy/FAISS operations. An LLM appears in exactly one place: the decoder's Tier-3 fallback (under 5% of decodes, capped at 80 tokens).
  • Fully local. Embeddings come from Ollama + snowflake-arctic-embed2 on your machine. No API key, no API cost, no data leaving your computer.
  • Forgetting is a feature. Memories decay like the Ebbinghaus curve, strengthen when recalled (Hebbian reinforcement), get consolidated nightly, and weak old ones are archived — so recall stays sharp instead of drowning in noise.

Quick Start

You need Python 3.11+ and Ollama installed.

# 1. Pull the embedding model (one time)
ollama pull snowflake-arctic-embed2

# 2. Install the lkhu CLI
pipx install git+https://github.com/iddk0321/lkhu
# once published to PyPI: pipx install lkhu

# 3. One-time setup: codebook + Claude Desktop MCP registration
lkhu install

# 4. Add lkhu to Claude Code as a plugin
claude plugin marketplace add iddk0321/lkhu
claude plugin install lkhu@lkhu

Restart Claude Code — done. From now on, lkhu injects recent memories at session start, recalls related memories on every prompt, and saves the conversation automatically. You never have to say "remember this" (though you can). Check everything is wired up with:

lkhu doctor

Per-OS notes: macOS · Linux · Windows. To remove: claude plugin uninstall lkhu@lkhu and lkhu uninstall (your data and codebook are preserved).

How it works

Encoding. Each memory's scent is 0.6 × semantic + 0.4 × structural. The semantic part is the snowflake-arctic-embed2 embedding; the structural part binds extracted key/value pairs (files, programming languages) to fixed unitary key vectors with circular convolution, then bundles them. Keys live in an append-only codebook generated once at install and backed up three times — new keys can be auto-discovered, but existing key vectors are never changed or regenerated.

Recall. The query scent goes to FAISS (top-K×3 candidates), which get re-ranked by similarity × (0.6 + 0.2 × strength + 0.2 × recency). Similarity is the primary, query-conditional signal; strength and recency are multiplicative modulators, not additive bonuses — so a globally-strong but off-topic memory can never outrank a clearly more similar one. Genuine hits (similarity ≥ 0.58) get a Hebbian strength boost (×1.05); every returned memory's access count still ticks up. The winners are bundled into one composite scent. No LLM involved.

Decoding (3-tier). Turning a scent back into language: ① short audit excerpts (~70% of cases), ② unbinding key vectors from the composite and matching against a local vocabulary (~25%), ③ LLM fallback capped at 80 tokens (<5% — and if no LLM is wired in, which is the default install, this tier degrades to a plain audit excerpt: zero LLM calls even here). A natural-language shadow copy (audit_text) is always kept for your visibility — but it's never the search target.

Biomimetic lifecycle. Daily at 03:00 UTC: strength decays ×0.99 and each session's memories consolidate into a summary scent (a weighted vector sum — 0 LLM calls). Weekly on Sunday: near-duplicates (cosine > 0.95) merge, and memories weaker than 0.1 and older than 30 days are archived, not deleted. See neuroscience mapping and architecture.

Multilingual by construction. snowflake-arctic-embed2 is a multilingual embedder and lkhu has no per-language keyword lists, so memories work across languages. Example (Korean input shown for illustration):

lkhu remember "우리 팀 백엔드는 FastAPI를 쓴다"   # stored in Korean
lkhu recall "which web framework does the team use"  # recalled in English

How is this different from claude-mem?

claude-mem is the pioneering memory plugin for Claude Code, and lkhu openly borrows from its UX: hooks-based automatic memory, plugin distribution, <private> tags, and a local web viewer all appeared there first. The difference is the layer underneath — claude-mem remembers in language, lkhu remembers in vectors.

claude-mem lkhu
Memory representation Natural-language summaries (AI-compressed observations) 1024-dim latent vectors ("scents") via VSA/HRR; NL kept only as an audit shadow
LLM calls Claude API compresses observations (e.g. at SessionEnd) 0 in the pipeline; Tier-3 decode fallback only (<5%, ≤80 tokens)
Privacy / locality Summarization goes through the Anthropic API Fully local (Ollama embedding); no API key, no API cost
Runtime stack TypeScript: Node 20+, Bun worker, SQLite+FTS5, Chroma (needs uv) Python 3.11+ only: numpy, faiss-cpu, SQLite, FastMCP — one pipx install
Retrieval cost Progressive disclosure: ~50–100 tokens/result, ~500–1000/detail Composite scent decoded to a few short lines; Tiers 1–2 cost 0 LLM tokens
Lifecycle / forgetting Persistent archive; everything kept and searchable Decay, Hebbian reinforcement, consolidation, cleanse — designed to forget
Web UI Viewer at localhost:37777, plus Telegram/Discord/Slack feeds Built-in dashboard (lkhu dashboard): lifecycle, strength/age charts, memory table
Multi-language Hybrid FTS5 keyword + semantic search snowflake-arctic-embed2 multilingual embeddings; no language-specific keyword lists

Pick claude-mem if you want a searchable, citable record of exactly what happened: full-text search over past sessions, rich observation detail, citations, chat-platform feeds, and a mature, battle-tested ecosystem. Keeping everything in natural language is precisely what makes that possible.

Pick lkhu if you want memory as a cheap, private background sense: no API spend on remembering, nothing leaving your machine, a single-language Python stack, and a system that compresses and forgets on its own like a brain does. The trade-off is honest — lkhu can't grep your past verbatim, because the past isn't stored as text.

They're different answers to the same question, and you can learn a lot by reading both. Longer write-up: docs/comparison.md.

What's inside

Automatic memory (hooks). Three Claude Code hooks, all zero-LLM: SessionStart injects recent memories, UserPromptSubmit recalls related memories and saves your prompt, Stop saves the assistant's final reply. System noise and <private>…</private> blocks are stripped before saving, and code/tool dumps are stripped from assistant replies. Details: docs/auto-memory.md.

MCP tools. Claude can call recall, remember, forget, recall_session, status, and export directly. Reference: docs/api-reference.md.

CLI. The lkhu command for inspection and control:

Command What it does
lkhu install / lkhu uninstall Set up / remove (codebook + Claude Desktop MCP; data preserved)
lkhu doctor Diagnose Ollama, codebook, MCP, hooks, daemon
lkhu status Memory counts, kinds, strength stats, codebook info
lkhu remember "..." --kind fact Store a memory explicitly
lkhu recall "query" --k 5 Search memories (debugging)
lkhu forget "query" --confirm Archive matching memories (audit preserved)
lkhu dashboard Open the web dashboard in your browser
lkhu export / lkhu import <file> Move audit data between machines as JSONL
lkhu backup Snapshot the codebook and database
lkhu eval Score recall / noise / multilingual / save-filter on a fixed gold corpus (isolated; never touches your memories)
lkhu reembed Rebuild all memory vectors with the current embedding model (run after switching models)

Dashboard. A self-contained local web page served by the daemon — stat cards, lifecycle flow, strength/age distributions, and a sortable memory table that refreshes every 5 seconds.

Daemon architecture. A single resident daemon owns the engine (SQLite + FAISS); hooks, the MCP server, and the dashboard are thin HTTP clients of it, so they always see one consistent index. It starts automatically when needed. Storage details: docs/storage.md.

Development

git clone https://github.com/iddk0321/lkhu
cd lkhu
python3.11 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                             # Ollama-dependent tests are skipped by default
ruff format && ruff check && mypy src

CI runs on ubuntu/macos/windows × Python 3.11/3.12/3.13. See CONTRIBUTING.md.

Docs

License

Apache License 2.0 — see LICENSE and NOTICE.

Built on the shoulders of: Tony Plate's Holographic Reduced Representations (2003), Snowflake Arctic Embed 2.0, FAISS, FastMCP, and the Model Context Protocol. UX inspiration: claude-mem.

Metadata

Release files for lkhu 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 lkhu 0.1.0
File Size Uploaded Provenance Actions
lkhu-0.1.0.tar.gz 148.0 kB With provenance Details for lkhu-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lkhu 0.1.0
File Interpreter ABI Platform Actions
lkhu-0.1.0-py3-none-any.whl Python 3 none any Details for lkhu-0.1.0-py3-none-any.whl

Total release size: 231.6 kB

Release files / lkhu-0.1.0.tar.gz

Download URL lkhu-0.1.0.tar.gz
Size 148.0 kB
Tags Source
SHA-256 checksum
How to use checksums
cced88914a76d1e0c429b96b0899db058483d4237db3a9a387bbaa3dc10764e7
BLAKE2b-256 checksum
How to use checksums
a8611274a0f5791b9a8f0a03b450d1eb4cacc74859a91a1d7e088fdeee32dea1
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 15, 2026.

Transparency log

Release files / lkhu-0.1.0-py3-none-any.whl

Download URL lkhu-0.1.0-py3-none-any.whl
Size 83.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
97cdf8ecd2655ea7cdab3f07bbfb8dc9b12dfa09fc956208ad413a47e8324eb1
BLAKE2b-256 checksum
How to use checksums
11ee845852bccb286a75631f011d2094ae86feea167e07ba8f7a76d80d1897bb
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 15, 2026.

Transparency log

Security for lkhu 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 lkhu-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 15, 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