Metadata-Version: 2.4
Name: hcr-memory
Version: 0.5.1
Summary: Persistent developer memory layer for AI coding tools — decisions, context, and knowledge that survive across sessions
Author-email: Rishi Praseeth Krishnan <praseethintegra@gmail.com>
License: Proprietary
Project-URL: Homepage, https://pypi.org/project/hcr-memory/
Keywords: mcp,ai,context,developer-tools,cursor,claude-code,windsurf,memory,cognitive
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: server
Requires-Dist: fastapi>=0.111.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "server"
Requires-Dist: aiohttp>=3.9.0; extra == "server"
Requires-Dist: cryptography>=41.0.0; extra == "server"
Requires-Dist: supabase>=2.0.0; extra == "server"
Provides-Extra: embeddings
Requires-Dist: sqlite-vec>=0.1.0; extra == "embeddings"
Requires-Dist: numpy>=1.24.0; extra == "embeddings"
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: cross-encoder>=0.0.1; extra == "embeddings"
Provides-Extra: google
Requires-Dist: google-genai>=1.0.0; extra == "google"
Provides-Extra: all
Requires-Dist: hcr-memory[server]; extra == "all"
Requires-Dist: hcr-memory[embeddings]; extra == "all"
Requires-Dist: hcr-memory[google]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: hcr-memory[all]; extra == "dev"
Dynamic: license-file

# HCR -- Persistent Developer Memory for AI Coding Tools

[![PyPI](https://img.shields.io/pypi/v/hcr-memory)](https://pypi.org/project/hcr-memory/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/hcr-memory/)
[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)

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

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

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

```json
{
  "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

```bash
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](LICENSE) for full terms.

---

[Report an Issue](mailto:praseethintegra@gmail.com) | [Contact](mailto:praseethintegra@gmail.com)
