hcr-memory 0.5.0

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

Hybrid Cognitive Runtime (HCR)

The Brain Behind Your AI Assistant

Enterprise-grade state management infrastructure for AI-powered development tools

---

Overview

Hybrid Cognitive Runtime (HCR) is a state-based cognitive execution system that eliminates the #1 developer pain point: context loss.

Traditional AI assistants are stateless—every session starts from zero, requiring developers to spend 10+ minutes re-explaining their work. HCR solves this by making intelligence persistent through structured cognitive state.

The Problem

• 48% of AI-generated code has security vulnerabilities due to context gaps
• Developers waste 10+ minutes per session rebuilding context
• AI assistants have no memory across sessions, devices, or conversations
• Enterprise teams lack audit trails and context governance

The Solution

HCR provides a persistent cognitive state layer that:

• Remembers context across sessions, models, and projects
• Reduces token usage by 10-100x (2000 → 200 tokens)
• Enables instant resume in <10 seconds
• Provides enterprise governance with audit trails and RBAC

Value Proposition

Metric	Traditional AI	HCR
Context Rebuild Time	10+ minutes	<10 seconds
Token Usage per Session	2000+ tokens	200 tokens
Sessions Without Re-Explanation	0%	>80%
Cross-Session Memory	❌ None	✅ Full
Enterprise Governance	❌ Limited	✅ RBAC + Audit

---

Enterprise Features

Resume Without Re-Explaining

Our flagship feature that eliminates context re-explanation overhead.

• Instant Context Recovery: Resume work in <10 seconds after any time gap
• Intelligent Task Inference: Automatically detect what you were working on
• Progress Tracking: Know exactly how far you got before the break
• Smart Suggestions: AI-powered next action recommendations

State Persistence

Enterprise-grade state management with Git-like versioning.

• Git-like Versioning: State hashes, commit messages, parent references
• Compression: gzip compression for efficient storage
• Encryption: Enterprise encryption for sensitive state data
• Cross-Project State: Share cognitive state across multiple projects
• Thread-Safe Operations: Lock-based concurrent access support

Security & Governance

Built for enterprise security and compliance requirements.

• Role-Based Access Control (RBAC): Developer, Admin, Auditor, Service roles
• Granular Permissions: READ_STATE, WRITE_STATE, DELETE_STATE, VIEW_AUDIT_LOG
• Audit Logging: Complete audit trail with query capabilities
• Compliance Reporting: GDPR, SOC2, HIPAA, ISO27001 checks
• User Management: Create, authenticate, authorize users

MCP Integration

Universal IDE integration through Model Context Protocol.

• 32 MCP Tools: Full state management, causal graph analysis, task inference, session management, version control, search, recommendations, agent lifecycle (preflight/postflight), triggers, shared state, and more
• 3 MCP Resources: State, causal-graph, task endpoints
• 2 MCP Prompts: Resume session, context-aware coding
• Dual Transport: Stdio (Claude/Cursor/Windsurf) + HTTP (web)
• Commercial Ready Architecture: Asyncio, non-blocking, full concurrency

Web Dashboard

Real-time state visualization and monitoring.

• Live Metrics: Token efficiency, confidence, uncertainty, active states
• Causal Graph Visualization: Interactive ReactFlow with animated edges
• State Evolution Timeline: Git-like version history browser
• System Health Monitor: Component health dashboard
• Risk Heatmaps: Fragility scoring and centrality analysis

---

Architecture

Cognitive State Fabric (CSF) — v2.0

The intelligence layer powering HCR's memory:

Layer	Component	What it does
Storage	CSOStore (SQLite + WAL)	Causally-linked CSO records, indexed by type/scope
Embedding	EmbeddingStore (sqlite-vec)	ANN vector search via Ollama or sentence-transformers
Centrality	CausalCentralityScorer	BFS reachability scoring — high-impact CSOs decay slower
Projection	CognitiveProjection	Centrality-ranked, decay-filtered live state for each agent call
Soft links	generate_soft_links	Semantic k-NN auto-detects implicit causal edges (threshold 0.82)
Episodes	BOCPDSegmenter	Bayesian changepoint detection segments event streams into work sessions
Fusion	reciprocal_rank_fusion + mmr_select	Merges semantic + causal results; selects diverse top-k
Prospective	prospective.py	TRIGGER CSOs inject reminders when matching file is edited (5th memory type)
Learned fusion	FeedbackStore	Learns RRF weights from agent session outcomes via least-squares

Core Components (Legacy / Low-Level)

Hybrid Cognitive Operator (HCO)

The fundamental unit of reasoning in HCR.

An HCO is the smallest executable unit of reasoning.

HCO = (
    S_in,        # input cognitive state
    Φ_n,         # neural operator (handles ambiguity)
    Φ_s,         # symbolic operator (rules / logic)
    Φ_c,         # causal operator (dependencies)
    Π,           # policy selector
    ΔS           # state transition
)

Cognitive State (S)

Rich, multi-modal state representation.

S = {
  latent: vector(n),         # compressed representation
  symbolic: {
    facts: [],
    rules: [],
    constraints: []
  },
  causal: {
    dependencies: [],
    effects: []
  },
  meta: {
    confidence: float,
    uncertainty: float,
    timestamp: t
  }
}

System Architecture

┌─────────────────────────────────────────────────────────┐
│                    Hybrid Cognitive Runtime             │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐      ┌──────────────┐               │
│  │  Input State │─────▶│  HCO Engine  │               │
│  │     (S_in)   │      │              │               │
│  └──────────────┘      └──────┬───────┘               │
│                                │                       │
│                                ▼                       │
│                        ┌──────────────┐               │
│                        │  Policy (Π)  │               │
│                        └──────┬───────┘               │
│                               │                       │
│              ┌────────────────┼────────────────┐      │
│              ▼                ▼                ▼      │
│        ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│        │ Neural   │    │Symbolic  │    │ Causal   │   │
│        │  (Φ_n)   │    │  (Φ_s)   │    │  (Φ_c)   │   │
│        └────┬─────┘    └────┬─────┘    └────┬─────┘   │
│             │              │              │          │
│             └──────────────┼──────────────┘          │
│                            │                         │
│                            ▼                         │
│                      ┌──────────┐                   │
│                      │ ΔS (State │                   │
│                      │Transition)│                   │
│                      └────┬─────┘                   │
│                           │                         │
│                           ▼                         │
│                  ┌──────────────┐                  │
│                  │ Output State │                  │
│                  │   (S_next)   │                  │
│                  └──────────────┘                  │
│                                                 │
├─────────────────────────────────────────────────┤
│              Operator Registry & Storage          │
├─────────────────────────────────────────────────┤
│  • HCO Catalog        • State History            │
│  • Operator Sequences • Learning Metrics         │
│  • Performance Data   • Feedback Loops           │
└─────────────────────────────────────────────────┘

Getting Started

1. Install

pip install hcr-mcp
hcr init          # creates .hcr/ in your project
hcr auth login    # authenticate (opens browser) — optional, see Local-only below

Requires Python 3.10+.

Full retrieval stack (embeddings + reranker, ~500 MB first run):

pip install "hcr-mcp[embeddings]"

Local-only mode — no account needed:

pip install hcr-mcp
hcr init
hcr-mcp   # starts stdio server, no auth required

2. Add to your IDE

Add to .mcp.json (Claude Code / Cursor / Windsurf / any MCP-compatible IDE):

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

Restart your IDE. hcr_preflight will now appear in your AI tool list.

Minimum requirements: Python 3.10+, 50 MB disk (base), 550 MB (with embeddings). No Docker, no Redis, no external DB.

3. Use with your AI tool

HCR works via MCP — no code changes needed. After hcr init, restart your IDE. The AI assistant now has access to hcr_preflight, hcr_remember, and the full memory tool suite.

# Check everything is working
hcr status

# Resume context after a break
hcr resume

Troubleshooting

Problem	Fix
hcr: command not found	Restart terminal or run pip show hcr-mcp to verify install
MCP tools not showing	Restart IDE after hcr init
Embedding errors	Run pip install -e ".[embeddings]" for semantic search

---

Installation (Advanced)

Development install from source

git clone https://github.com/PantheraLabs/HybridCognitiveRuntime.git
cd HybridCognitiveRuntime
pip install -e .

With semantic search: pip install -e ".[embeddings]"

First-time setup

hcr login         # Authenticate (opens browser for cloud features)
hcr init --auto   # Initialize project + wire up IDE

Quick Start

Resume Your Session

# Resume with context
hcr resume

# Check system status
hcr status

# Launch web dashboard
hcr dashboard

Using the Engine API

from hcr.engine.engine_api import HCREngine, EngineEvent

# Initialize engine
engine = HCREngine(project_path=".")

# Process an event
engine.update_from_environment(EngineEvent(
    event_type="file_edit",
    data={"path": "src/core/hco_engine.py"}
))

# Infer context using real LLM intelligence
context = engine.infer_context()
print(f"Task: {context.current_task}")
print(f"Next Action: {context.next_action}")

IDE Integration

HCR integrates with your IDE via MCP (Model Context Protocol):

• Windsurf/Cascade: Automatic context capture and resume
• Claude Desktop: Native HCR tools available
• Cursor: Full MCP server integration
• VS Code: Extension available (coming soon)

Configure your IDE's MCP settings using the CLI (e.g. hcr setup-ide --auto), or point to:

command: python -m hcr.product.integrations.mcp_server_stdio

Security & Compliance

Security Features

• RBAC: Role-based access control with granular permissions
• Audit Logging: Complete audit trail of all state operations
• Encryption: State data encryption at rest and in transit
• Authentication: Secure user authentication and authorization
• Data Isolation: Project-level state isolation

Compliance Standards

• GDPR: Data protection and privacy compliance
• SOC2: Security and availability controls
• HIPAA: Healthcare data protection (enterprise tier)
• ISO27001: Information security management

Data Privacy

• All cognitive state data remains under your control
• Optional local-only mode with no external data transmission
• Configurable data retention policies
• Export capabilities for data portability

---

Testing & Quality

# Run full test suite
python -m pytest tests/ -v

# Run specific test
python -m pytest tests/test_engine_api.py -v

# System diagnostics
hcr doctor
hcr doctor --format json

Test Coverage: 384 tests passing, 6 skipped (100% pass rate)

Quality Metrics:

• Code coverage: >90%
• Integration tests: Full MCP server verification (24 tools)
• Performance benchmarks: Token efficiency validated
• Security audit: B+ grade (see docs/CODE_REVIEW_2026_04_28.md)

Project Structure

HybridCognitiveRuntime/
├── src/
│   ├── state/              # State representation & transitions
│   ├── operators/          # HCO implementations (Neural, Symbolic, Causal)
│   ├── core/               # Execution engine & orchestration
│   ├── llm/                # LLM Provider abstraction
│   ├── causal/             # Causal graph & dependency analysis
│   └── engine_api.py       # High-level product API
├── product/
│   ├── config.py           # Layered configuration system
│   ├── caching/            # LLM request cache
│   ├── server/             # HTTP engine API server
│   ├── cli/                # Professional CLI (init, resume, status, dashboard)
│   ├── state_capture/      # Git tracker, file watcher, terminal monitor
│   ├── storage/            # State persistence, locking, semantic decay
│   ├── hco_wrappers/       # Developer context HCOs
│   ├── integrations/       # MCP server, IDE bridges
│   ├── security/           # RBAC, audit logging, compliance
│   └── daemon/             # Git hook triggers & watchers
├── web/
│   └── web-ui/             # React dashboard with ReactFlow visualization
├── examples/               # Usage examples
├── tests/                  # Unit tests & benchmarks
└── docs/                   # Documentation
    ├── project_memory.md   # Project decisions & context
    ├── architecture.md     # System architecture
    ├── tasks.md            # Development roadmap
    └── dev_log.md          # Development log

Key Features

Core Capabilities

• Real Intelligence: Integrated with Groq, Gemini, Ollama, OpenAI, and Anthropic
• State-Based Reasoning: Persistent cognitive state across operations
• Zero-Latency Processing: Events processed instantly; LLM called lazily
• Heuristic Fallback: Works offline/without keys using pattern matching
• Response Caching: Hash-based caching to minimize LLM costs

Developer Experience

• One-Command Setup: hcr init --auto configures everything automatically
• Universal IDE Support: MCP integration for Windsurf, Claude, Cursor
• Professional CLI: Intuitive commands for all operations
• Web Dashboard: Real-time state visualization and monitoring
• Smart Resume: Context recovery in <10 seconds

Enterprise Features

• RBAC: Role-based access control with granular permissions
• Audit Logging: Complete audit trail for compliance
• State Versioning: Git-like state history and rollback
• Cross-Project State: Share cognitive state across projects
• Compliance Reporting: GDPR, SOC2, HIPAA, ISO27001

Why HCR?

The Problem

Developer tools today force you to re-explain your context every time you switch windows, devices, or conversations:

• VS Code doesn't remember what you were doing
• AI assistants start fresh every chat
• Context is lost across sessions
• 48% of AI-generated code has security vulnerabilities due to context gaps
• Developers waste 10+ minutes per session rebuilding context

The Solution

HCR captures and persists cognitive state — not just files, but what you were thinking:

Developer opens project
    ↓
System loads saved cognitive state from .hcr/state/
    ↓
Captures current context (git diff, open files, errors)
    ↓
Updates cognitive state with current reality
    ↓
Runs HCO sequence: ingest → infer → suggest
    ↓
Outputs: [Current Task] [Progress %] [Next Action]

Results

• 80%+ sessions resumed without typing
• 10-100x token reduction (2000 → 200 tokens)
• <10 seconds to first productive action
• 30-75% developer productivity increase

Use Cases

Use Case	How HCR Helps
Resume Work	Know exactly where you left off after a break, weekend, or vacation
Code Review	Track intent behind changes, not just diffs. Understand the "why"
Onboarding	New team members see the complete context and decision history
Debugging	Correlate errors with recent changes and developer intent
AI Assistants	Context persists across conversations, devices, and sessions
Enterprise Governance	Audit trails, compliance reporting, team-wide state management
Context Switching	Seamlessly switch between projects without losing momentum

Performance Metrics

Metric	Value
Session Resume Rate	>80% without typing
Token Reduction	10-100x vs traditional context rebuilding
Time to First Action	<10 seconds
Test Coverage	384 tests passing, 6 skipped (100% pass rate)
LLM Providers	Groq, Gemini, Ollama, OpenAI, Anthropic
MCP Tools	32 tools, 3 resources, 2 prompts
Enterprise Security	RBAC + Audit + Compliance

Development Status

Completed Phases ✅

• Phase 1: Core Infrastructure (State, Operators, Engine)
• Phase 2: Real LLM Integration (Multi-provider support)
• Phase 3: Autonomous Context Extraction (Daemon, file watcher)
• Phase 4: State Visualizer (Web dashboard with ReactFlow)
• Phase 5: Commercial SaaS UI (Professional web interface)

Current Focus 🔄

• VS Code Extension development
• Enterprise partnerships
• Advanced predictive features

Roadmap 📋

See docs/tasks.md for detailed development roadmap.

Support & Resources

Documentation

• Project Memory - Design decisions and context
• Architecture - System architecture details
• Tasks - Development roadmap
• Product Spec - Feature specifications

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Enterprise Support

For enterprise licensing, SLAs, and dedicated support, contact the team.

---

License

This project is licensed under a Proprietary License. The source code is visible for reference only.

No license is granted for:

• Commercial use without written consent
• Modification or derivative works
• Distribution or sublicensing

See the LICENSE file for full terms. For licensing inquiries, please contact the author.

---

Links

• Documentation: docs/
• Examples: examples/
• Web Dashboard: hcr dashboard
• CLI Reference: hcr --help

---

Built with ❤️ by PantheraLabs

Intelligence should persist. Context should resume.

The Brain Behind Your AI Assistant

📄 License

This project is licensed under a Proprietary License. The source code is visible for reference only.

No license is granted for:

• Commercial use without written consent
• Modification or derivative works
• Distribution or sublicensing

See the LICENSE file for full terms. For licensing inquiries, please contact the author.

🔗 Links

• Documentation: docs/
• Examples: examples/
• Issues: GitHub Issues
• Discussions: GitHub Discussions