Metadata-Version: 2.4
Name: hcr-memory
Version: 0.5.0
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://github.com/PantheraLabs/HybridCognitiveRuntime
Project-URL: Repository, https://github.com/PantheraLabs/HybridCognitiveRuntime
Project-URL: Documentation, https://github.com/PantheraLabs/HybridCognitiveRuntime#readme
Project-URL: Issues, https://github.com/PantheraLabs/HybridCognitiveRuntime/issues
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

<div align="center">
  <img src="assets/images/logo.png" alt="HCR Logo" width="200"/>
  <h1>Hybrid Cognitive Runtime (HCR)</h1>
  <p><strong>The Brain Behind Your AI Assistant</strong></p>
  <p>Enterprise-grade state management infrastructure for AI-powered development tools</p>
  <p>
    <a href="#quick-start"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.8+"></a>
    <a href="#enterprise-features"><img src="https://img.shields.io/badge/enterprise-ready-success.svg" alt="Enterprise Ready"></a>
    <a href="#security"><img src="https://img.shields.io/badge/security-RBAC%20%7C%20Audit%20%7C%20Compliance-brightgreen.svg" alt="Security"></a>
    <a href="#integrations"><img src="https://img.shields.io/badge/MCP-Universal%20IDE%20Integration-purple.svg" alt="MCP"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-Proprietary-red.svg" alt="License: Proprietary"></a>
  </p>
</div>

---

## 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.

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

```bash
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):
```bash
pip install "hcr-mcp[embeddings]"
```

**Local-only mode** — no account needed:
```bash
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):

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

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

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

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

### First-time setup

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

## Quick Start

### Resume Your Session

```bash
# Resume with context
hcr resume

# Check system status
hcr status

# Launch web dashboard
hcr dashboard
```

### Using the Engine API

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

```bash
# 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](docs/tasks.md) for detailed development roadmap.

## Support & Resources

### Documentation
- [Project Memory](docs/project_memory.md) - Design decisions and context
- [Architecture](docs/architecture.md) - System architecture details
- [Tasks](docs/tasks.md) - Development roadmap
- [Product Spec](product/PRODUCT_SPEC.md) - Feature specifications

### Community
- **Issues**: [GitHub Issues](https://github.com/PantheraLabs/HybridCognitiveRuntime/issues)
- **Discussions**: [GitHub Discussions](https://github.com/PantheraLabs/HybridCognitiveRuntime/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](LICENSE) file for full terms. For licensing inquiries, please contact the author.

---

## Links

- **Documentation**: [docs/](docs/)
- **Examples**: [examples/](examples/)
- **Web Dashboard**: `hcr dashboard`
- **CLI Reference**: `hcr --help`

---

<div align="center">
  <p><strong>Built with ❤️ by PantheraLabs</strong></p>
  <p><em>Intelligence should persist. Context should resume.</em></p>
  <p><small>The Brain Behind Your AI Assistant</small></p>
</div>

## 📄 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](LICENSE) file for full terms. For licensing inquiries, please contact the author.

## 🔗 Links

- **Documentation**: [docs/](docs/)
- **Examples**: [examples/](examples/)
- **Issues**: [GitHub Issues](https://github.com/PantheraLabs/HybridCognitiveRuntime/issues)
- **Discussions**: [GitHub Discussions](https://github.com/PantheraLabs/HybridCognitiveRuntime/discussions)

