hcr-memory 0.5.0__py3-none-any.whl

hcr/.hcr/cpap_epoch.json

@@ -0,0 +1 @@
+{"epoch": "90af4049", "git_head": "", "frozen_at": "2026-05-29T06:21:56.605905+00:00", "cso_ids": [], "insertion_ranks": {}, "layer2_bytes": "## Project Memory\n"}

hcr/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+HCR — Hybrid Cognitive Runtime
+
+Persistent developer memory layer exposed as an MCP server.
+The key insight: AI tools are stateless. HCR provides the stateful substrate
+they lack — decisions, constraints, risks, and causal relationships that
+persist across sessions, tools, and teammates.
+
+HOW IT WORKS (3 layers):
+  1. hcr/engine/     — Core reasoning: CSO store, memory fabric, inference.
+  2. hcr/product/    — Product surface: MCP server, CLI, API, auth, storage.
+  3. .hcr/           — Per-project data: cso.db, embeddings.db, feedback.db.
+
+ENTRY POINTS:
+  python -m hcr.product.integrations.mcp_server_stdio   # MCP server (for IDEs)
+  hcr init / hcr status / hcr resume                    # CLI
+
+START READING:
+  hcr/engine/engine_api.py                              # HCREngine (central object)
+  hcr/product/integrations/mcp_server.py                # MCP tool dispatch
+  hcr/engine/cso/cso_model.py                           # What a CSO is
+"""
+
+__version__ = "0.5.0"
+

hcr/engine/__init__.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+hcr.engine — Core reasoning engine
+
+PACKAGE MAP — read in this order to understand the system:
+
+  engine_api.py       — HCREngine: the central object. Owns all stores,
+                        handles file-edit hot path, exposes the API that
+                        MCP tools call. Start here.
+
+  cso/                — CSO (Cognitive State Object) data model + SQLite store.
+                        cso_model.py: typed record (DECISION, CONSTRAINT, RISK,
+                        TASK, OUTCOME, ...) with causal_in/causal_out edges.
+                        cso_store.py: SQLite + WAL persistence at .hcr/cso.db.
+
+  memory/             — Cognitive State Fabric: retrieval intelligence.
+                        See memory/__init__.py for per-file descriptions.
+
+  causal/             — Causal analysis: AST dependency graph, impact BFS,
+                        event store for temporal reasoning.
+
+  inference/          — Inference engines: Causal Predictor, Constraint Learner,
+                        Session Narrator, Root Cause Tracer (hcr_why).
+
+  symbolic/           — SymbolicVerifier: fires rules against new CSOs,
+                        emits RISK CSOs when rules match.
+
+  llm/                — LLMProvider: unified interface for Groq / Gemini / Ollama.
+
+  state/              — CognitiveState dataclass + state transitions (legacy,
+                        kept for backwards compat alongside CSO v2.0 store).
+"""

hcr/engine/causal/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+HCR Causal Intelligence Package
+
+The Temporal Causal Graph — HCR's core moat.
+Tracks file dependencies, temporal event chains, and predicts impact.
+"""
+
+from .dependency_graph import DependencyGraph
+from .event_store import EventStore, CausalEvent
+from .impact_analyzer import ImpactAnalyzer
+from .cso_impact import query_cso_impact
+from .temporal_correlator import TemporalCorrelator
+
+__all__ = ["DependencyGraph", "EventStore", "CausalEvent", "ImpactAnalyzer", "query_cso_impact", "TemporalCorrelator"]

hcr/engine/causal/ast_extractor.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+AST Extractor
+
+Extracts semantic dependencies (imports, function calls, class usage)
+from Python source code to build the causal graph.
+"""
+
+import ast
+from pathlib import Path
+from typing import List, Dict, Set
+
+class DependencyExtractor(ast.NodeVisitor):
+    def __init__(self, current_module: str):
+        self.current_module = current_module
+        self.imports: Set[str] = set()
+        self.calls: Set[str] = set()
+
+    def visit_Import(self, node: ast.Import):
+        for alias in node.names:
+            self.imports.add(alias.name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom):
+        if node.module:
+            self.imports.add(node.module)
+        self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call):
+        if isinstance(node.func, ast.Name):
+            self.calls.add(node.func.id)
+        elif isinstance(node.func, ast.Attribute):
+            self.calls.add(node.func.attr)
+        self.generic_visit(node)
+
+def extract_dependencies(file_path: Path) -> Dict[str, List[str]]:
+    """Parse a python file and extract its dependencies."""
+    if not file_path.exists() or file_path.suffix != '.py':
+        return {"imports": [], "calls": []}
+
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        tree = ast.parse(content)
+        
+        # Simple module name extraction based on file path for this prototype
+        module_name = file_path.stem 
+        extractor = DependencyExtractor(module_name)
+        extractor.visit(tree)
+        
+        return {
+            "imports": list(extractor.imports),
+            "calls": list(extractor.calls)
+        }
+    except Exception as e:
+        # Ignore syntax errors or parsing issues for now
+        return {"imports": [], "calls": []}
+

hcr/engine/causal/co_change_miner.py

@@ -0,0 +1,96 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""Git co-change mining: extract file pairs frequently committed together."""
+
+import subprocess
+import logging
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+_MIN_CO_CHANGES = 3       # minimum co-occurrences to consider a relationship
+_MAX_COMMITS_SCAN = 500   # only scan recent history (performance)
+
+
+def mine_co_changes(
+    project_path: Path,
+    min_count: int = _MIN_CO_CHANGES,
+    max_commits: int = _MAX_COMMITS_SCAN,
+) -> Dict[str, List[Tuple[str, int]]]:
+    """
+    Parse git log and return co-change map: {file_path: [(co_changed_file, count), ...]}.
+    Only pairs with count >= min_count are included.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", f"--max-count={max_commits}", "--name-only", "--pretty=format:COMMIT"],
+            capture_output=True,
+            text=True,
+            cwd=str(project_path),
+            timeout=30,
+        )
+        if result.returncode != 0:
+            logger.debug("git log failed: %s", result.stderr[:200])
+            return {}
+        return _parse_co_changes(result.stdout, min_count)
+    except Exception as e:
+        logger.debug("co-change mining error: %s", e)
+        return {}
+
+
+def _parse_co_changes(git_log_output: str, min_count: int) -> Dict[str, List[Tuple[str, int]]]:
+    """Parse git log --name-only output into co-change pairs."""
+    pair_counts: Dict[Tuple[str, str], int] = defaultdict(int)
+
+    current_files: List[str] = []
+    for line in git_log_output.splitlines():
+        line = line.strip()
+        if line == "COMMIT":
+            # Process previous commit's files
+            if len(current_files) >= 2:
+                for i, f1 in enumerate(current_files):
+                    for f2 in current_files[i + 1:]:
+                        key = (min(f1, f2), max(f1, f2))
+                        pair_counts[key] += 1
+            current_files = []
+        elif line:
+            current_files.append(line)
+
+    # Process last commit
+    if len(current_files) >= 2:
+        for i, f1 in enumerate(current_files):
+            for f2 in current_files[i + 1:]:
+                key = (min(f1, f2), max(f1, f2))
+                pair_counts[key] += 1
+
+    # Build adjacency map
+    co_change_map: Dict[str, List[Tuple[str, int]]] = defaultdict(list)
+    for (f1, f2), count in pair_counts.items():
+        if count >= min_count:
+            co_change_map[f1].append((f2, count))
+            co_change_map[f2].append((f1, count))
+
+    # Sort each list by count desc
+    for path in co_change_map:
+        co_change_map[path].sort(key=lambda x: x[1], reverse=True)
+
+    return dict(co_change_map)
+
+
+def get_co_change_candidates(
+    file_path: str,
+    co_change_map: Dict[str, List[Tuple[str, int]]],
+) -> List[str]:
+    """Return list of co-changed file paths for a given file, sorted by frequency."""
+    # Normalize path separators
+    normalized = file_path.replace("\\", "/")
+    # Try exact match first, then suffix match
+    candidates = co_change_map.get(normalized, [])
+    if not candidates:
+        for k, v in co_change_map.items():
+            if k.endswith(normalized) or normalized.endswith(k):
+                candidates = v
+                break
+    return [f for f, _ in candidates]

hcr/engine/causal/cso_impact.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+CSO-graph-based impact analysis for hcr_analyze_impact (v2.0).
+
+Traverses causal_in edges stored in the CSOStore to find all files
+that are transitively impacted by a change to the given file_path.
+
+Semantic attention filter (Phase 2): when a query_embedding is provided,
+only traverse edges where the candidate CSO's embedding similarity to the
+query exceeds similarity_threshold. Prevents graph wandering.
+"""
+import logging
+from typing import Any, List, Optional, Set
+
+from hcr.engine.cso.cso_store import CSOStore
+
+_logger = logging.getLogger("HCR-CSOImpact")
+
+
+def query_cso_impact(
+    store: CSOStore,
+    file_path: str,
+    max_depth: int = 3,
+    query_embedding: Optional[List[float]] = None,
+    similarity_threshold: float = 0.65,
+    embedding_store: Optional[Any] = None,
+    feedback_store: Optional[Any] = None,
+) -> List[str]:
+    """Return files transitively impacted by a change to *file_path*.
+
+    Performs a semantic attention BFS over causal_in edges up to *max_depth* hops.
+    When query_embedding is provided, only expands edges where the candidate
+    CSO's embedding similarity exceeds similarity_threshold.
+
+    When embedding_store is provided, fuses the BFS result with a semantic ANN
+    search via Reciprocal Rank Fusion (RRF) for a richer ranked result list.
+
+    Args:
+        store:                Initialised CSOStore to query.
+        file_path:            The changed file (as stored in CSO payload["file_path"]).
+        max_depth:            Maximum BFS depth (clamped to >= 1).
+        query_embedding:      Optional embedding vector for semantic filtering.
+        similarity_threshold: Minimum cosine similarity to traverse an edge.
+        embedding_store:      Optional EmbeddingStore for RRF semantic fusion.
+
+    Returns:
+        List of file_path strings that are downstream of the given file.
+        Empty list if no causal edges exist for this file.
+    """
+    max_depth = max(1, max_depth)
+
+    all_csos = store.query(cso_type=None, limit=2000)
+
+    id_to_file: dict = {}
+    file_to_ids: dict = {}
+    for cso in all_csos:
+        fp = cso.payload.get("file_path", "")
+        if fp:
+            id_to_file[cso.id] = fp
+            file_to_ids.setdefault(fp, set()).add(cso.id)
+
+    frontier: Set[str] = set(file_to_ids.get(file_path, []))
+    visited: Set[str] = set(frontier)
+    impacted_files: Set[str] = set()
+
+    for _ in range(max_depth):
+        if not frontier:
+            break
+        next_frontier: Set[str] = set()
+        for cso in all_csos:
+            if not any(cause_id in frontier for cause_id in cso.causal_in):
+                continue
+            if cso.id in visited:
+                continue
+            # Semantic attention filter: skip if query provided and similarity low
+            if query_embedding and hasattr(cso, "_embedding") and cso._embedding:
+                from hcr.engine.memory.fusion import _cosine
+                if _cosine(cso._embedding, query_embedding) < similarity_threshold:
+                    continue
+            visited.add(cso.id)
+            next_frontier.add(cso.id)
+            fp = cso.payload.get("file_path", "")
+            if fp and fp != file_path:
+                impacted_files.add(fp)
+        frontier = next_frontier
+
+    # CSF Phase 2d: RRF fusion with semantic ANN search when embedding_store available
+    if embedding_store is not None:
+        try:
+            from hcr.engine.memory.fusion import reciprocal_rank_fusion
+            causal_ranked = [(fp, 1.0 / (i + 1)) for i, fp in enumerate(impacted_files)]
+            semantic_hits = embedding_store.search(file_path, top_k=20)
+            semantic_ranked = []
+            for cso_id, dist in semantic_hits:
+                fp = id_to_file.get(cso_id, "")
+                if fp and fp != file_path:
+                    semantic_ranked.append((fp, dist))
+            weights = None
+            if feedback_store is not None:
+                try:
+                    weights = feedback_store.get_weights()
+                except Exception:
+                    _logger.debug("Feedback weights lookup failed", exc_info=True)
+            fused = reciprocal_rank_fusion(semantic_ranked, causal_ranked, weights=weights)
+            return [fp for fp, _ in fused if fp]
+        except Exception:
+            _logger.debug("RRF fusion fallback to plain BFS", exc_info=True)
+
+    return list(impacted_files)

hcr/engine/causal/dependency_graph.py

@@ -0,0 +1,89 @@
+# Copyright (c) 2025-2026 Rishi Praseeth Krishnan. All rights reserved.
+# Proprietary and confidential. Unauthorized copying or distribution prohibited.
+"""
+Dependency Graph
+
+An in-memory directed graph representing file and functional dependencies
+derived from the AST and causal events.
+"""
+
+from typing import Dict, List, Set
+from pathlib import Path
+
+class DependencyGraph:
+    def __init__(self):
+        # Maps a node (file path or module) to a list of nodes it depends on
+        self.forward_edges: Dict[str, Set[str]] = {}
+        # Maps a node to a list of nodes that depend on it
+        self.reverse_edges: Dict[str, Set[str]] = {}
+        # Latent links discovered by LLM (cause, effect, type, reason)
+        self.latent_edges: List[dict] = []
+
+    def add_dependency(self, source: str, target: str):
+        """Add a directed edge from source to target (source depends on target)."""
+        if source not in self.forward_edges:
+            self.forward_edges[source] = set()
+        self.forward_edges[source].add(target)
+
+        if target not in self.reverse_edges:
+            self.reverse_edges[target] = set()
+        self.reverse_edges[target].add(source)
+
+    def add_latent_link(self, source: str, target: str, link_type: str = "latent", reason: str = ""):
+        """Add a latent link discovered by neural inference."""
+        self.latent_edges.append({
+            "source": source,
+            "target": target,
+            "type": link_type,
+            "reason": reason
+        })
+        # Also add to standard graph for impact analysis
+        self.add_dependency(source, target)
+
+    def get_metrics(self, node: str) -> dict:
+        """Calculate and return metrics for a specific node"""
+        from .metrics import MetricsAnalyzer
+        fragility = MetricsAnalyzer.calculate_fragility(node)
+        centrality = MetricsAnalyzer.calculate_centrality(
+            node, 
+            self.forward_edges, 
+            self.reverse_edges
+        )
+        return {
+            "fragility": fragility,
+            "centrality": centrality,
+            "risk_score": round((fragility + centrality) / 2, 2)
+        }
+
+    def to_dict(self) -> dict:
+        """Convert graph to dictionary with node metrics and latent links"""
+        nodes = list(set(list(self.forward_edges.keys()) + list(self.reverse_edges.keys())))
+        node_data = {node: self.get_metrics(node) for node in nodes}
+        
+        return {
+            "forward": self.forward_edges,
+            "reverse": self.reverse_edges,
+            "latent_links": self.latent_edges,
+            "metrics": node_data
+        }
+
+    def get_dependencies(self, node: str) -> List[str]:
+        """Get all nodes that the given node depends on."""
+        return list(self.forward_edges.get(node, set()))
+
+    def get_dependents(self, node: str) -> List[str]:
+        """Get all nodes that depend on the given node."""
+        return list(self.reverse_edges.get(node, set()))
+
+    def update_file_dependencies(self, file_path: str, dependencies: List[str]):
+        """Replace existing dependencies for a file with a new set."""
+        # Remove old forward edges
+        old_deps = self.forward_edges.get(file_path, set())
+        for target in old_deps:
+            if file_path in self.reverse_edges.get(target, set()):
+                self.reverse_edges[target].remove(file_path)
+                
+        # Set new dependencies
+        self.forward_edges[file_path] = set()
+        for target in dependencies:
+            self.add_dependency(file_path, target)