hcr-memory 0.5.0__tar.gz

hcr_memory-0.5.0/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, modification,
+distribution, or use of this software, via any medium, is strictly prohibited.
+
+For licensing inquiries, contact: praseethintegra@gmail.com

hcr_memory-0.5.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include hcr *.json *.yaml *.yml *.md
+recursive-include docs *.md
+exclude .env
+exclude .env.*
+prune .hcr
+prune .claude
+prune demo
+prune benchmark

hcr_memory-0.5.0/PKG-INFO

@@ -0,0 +1,632 @@
+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)
+