hcr-memory 0.5.1

Persistent developer memory layer for AI coding tools — decisions, context, and knowledge that survive across sessions

HCR -- Persistent Developer Memory for AI Coding Tools

pip install hcr-memory

---

The Problem

AI coding tools are stateless. Every session starts from zero -- your decisions, constraints, past failures, and architectural context are gone. Developers waste minutes re-explaining what they were doing, and AI assistants repeat mistakes they already made in a previous session.

The Solution

HCR is a persistent memory layer that sits behind your AI coding tools via MCP (Model Context Protocol).

• Captures decisions, constraints, risks, and observations as typed, causally-linked records (Cognitive State Objects)
• Tracks ripple effects through a causal dependency graph -- edit a file and see what downstream knowledge is affected
• Searches all project knowledge with semantic + BM25 hybrid retrieval and cross-encoder reranking
• Works with Claude Code, Cursor, Windsurf, and any MCP-compatible tool -- no code changes required

---

Quick Start

pip install hcr-memory        # install from PyPI
hcr init                      # initialize .hcr/ in your project
hcr status                    # show cognitive state summary
hcr doctor                    # verify installation and dependencies

To enable semantic search and reranking (~500 MB first download):

pip install "hcr-memory[embeddings]"

---

How It Works

HCR stores all project knowledge as Cognitive State Objects (CSOs) in a local SQLite database (.hcr/cso.db). Each CSO is typed (DECISION, CONSTRAINT, RISK, OBSERVATION, TASK, etc.) and linked to other CSOs via causal edges, forming a directed graph.

The memory fabric retrieves relevant context using three fused channels: time-decay ranking, BM25 keyword search, and ANN embedding search -- combined via reciprocal rank fusion with learned weights, then reranked by a cross-encoder. A background prefetcher caches projections so tool calls hit zero compute latency.

The CPAP protocol (Causal Prefix Alignment Protocol) serializes context into a three-layer format where the first two layers are byte-identical between calls, achieving ~98% prompt cache hit rates.

---

CLI Commands

Command	Description
hcr init	Initialize HCR in the current project (creates .hcr/ directory)
hcr status	Show cognitive state summary -- memory count, decisions, active tasks
hcr search <query>	Semantic + keyword search over all project memories
hcr remember <text>	Store a decision, constraint, or risk (--type decision|constraint|risk)
hcr forget <id>	Remove a specific memory (--all to clear everything)
hcr doctor	Run diagnostics -- checks dependencies, database health, embedding status
hcr login	Authenticate with HCR cloud (opens browser)
hcr logout	Log out of HCR cloud
hcr sync	Sync local state with cloud (--push / --pull)
hcr export	Export memories (--json or --md)
hcr setup	Install lifecycle hooks for AI tools (default: Claude Code)

Running hcr with no arguments starts an interactive REPL with /command syntax, fuzzy matching, and shell passthrough (!git status).

---

MCP Integration

Add HCR to your AI tool by placing this in .mcp.json (Claude Code, Cursor, Windsurf):

{
  "mcpServers": {
    "hcr": {
      "command": "hcr-mcp",
      "args": []
    }
  }
}

Restart your IDE. The AI assistant now has access to 11 memory tools:

Tool	Purpose
hcr_preflight	Session start -- returns ranked decisions, constraints, risks, and narrative
hcr_postflight	Session end -- records outcome, mines narration into new CSOs
hcr_get_state	Lightweight state summary
hcr_edit	Record a file edit -- triggers causal warnings if downstream knowledge is affected
hcr_remember	Write a decision, constraint, or risk
hcr_fail	Log a failure -- returns similar past failures and their resolutions
hcr_resolve	Close an investigation -- updates pattern confidence
hcr_read_decisions	Read stored decisions and constraints
hcr_analyze_impact	Causal BFS impact analysis for a file (or full graph summary)
hcr_search	Semantic + BM25 search over all CSOs
hcr_get_recommendations	Current task, next action, and AI-generated suggestions

---

Claude Code Hooks

hcr setup claude-code

This installs 5 lifecycle hooks into Claude Code's settings for passive memory capture:

• SessionStart -- injects cognitive state on session start
• UserPromptSubmit -- provides a live digest on every prompt
• PostToolUse -- captures file edits automatically
• PreCompact -- preserves memory through context compaction
• Stop -- labels session outcome for the feedback learning loop

Use hcr setup --uninstall to remove hooks, or hcr setup --project for project-level installation.

---

Requirements

• Python 3.10+
• Base install: pip install hcr-memory (Rich, httpx, PyYAML, python-dotenv)
• Semantic search: pip install "hcr-memory[embeddings]" (sentence-transformers, sqlite-vec, cross-encoder, numpy)
• Cloud/API server: pip install "hcr-memory[server]" (FastAPI, uvicorn, Supabase)
• Google LLM: pip install "hcr-memory[google]" (google-genai)
• Everything: pip install "hcr-memory[all]"

No Docker, no Redis, no external database. Local SQLite only.

---

License

Proprietary. Copyright 2025-2026 Rishi Praseeth Krishnan. All rights reserved.

This software is distributed exclusively via PyPI. No license is granted for reproduction, modification, reverse engineering, or redistribution. See LICENSE for full terms.

---

Report an Issue | Contact