openmem-engine 0.1.0__py3-none-any.whl

openmem/__init__.py

@@ -0,0 +1,4 @@
+from .engine import MemoryEngine
+from .models import Edge, Memory, ScoredMemory
+
+__all__ = ["MemoryEngine", "Memory", "Edge", "ScoredMemory"]

openmem/activation.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import SQLiteStore
+
+
+def spread_activation(
+    seed_activations: dict[str, float],
+    store: SQLiteStore,
+    max_hops: int = 2,
+    decay_per_hop: float = 0.5,
+) -> dict[str, float]:
+    """Spreading activation over the memory graph.
+
+    Starting from seed nodes (typically BM25 hits), propagates activation
+    along edges with decay per hop. Returns memory_id → activation_score.
+    """
+    activations = dict(seed_activations)
+    frontier = set(seed_activations.keys())
+
+    for hop in range(max_hops):
+        next_frontier: dict[str, float] = {}
+        for node_id in frontier:
+            for edge, neighbor in store.get_neighbors(node_id):
+                spread = activations[node_id] * edge.weight * (decay_per_hop ** (hop + 1))
+                if spread > activations.get(neighbor.id, 0):
+                    next_frontier[neighbor.id] = spread
+                    activations[neighbor.id] = spread
+        frontier = set(next_frontier.keys())
+        if not frontier:
+            break
+
+    return activations

openmem/conflict.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .models import ScoredMemory
+from .scoring import recency_score, strength_score
+
+if TYPE_CHECKING:
+    from .store import SQLiteStore
+
+
+def detect_and_resolve_conflicts(
+    scored: list[ScoredMemory],
+    store: SQLiteStore,
+    now: float | None = None,
+) -> list[ScoredMemory]:
+    """Scan activated memories for contradicts edges. Demote the weaker side."""
+    if len(scored) < 2:
+        return scored
+
+    id_set = {s.memory.id for s in scored}
+    by_id = {s.memory.id: s for s in scored}
+    demoted: set[str] = set()
+
+    for sm in scored:
+        edges = store.get_edges(sm.memory.id)
+        for edge in edges:
+            if edge.rel_type != "contradicts":
+                continue
+            other_id = edge.target_id if edge.source_id == sm.memory.id else edge.source_id
+            if other_id not in id_set or other_id in demoted or sm.memory.id in demoted:
+                continue
+
+            # Rank by strength * confidence * recency
+            a = sm
+            b = by_id[other_id]
+            rank_a = a.memory.strength * a.memory.confidence * recency_score(a.memory, now)
+            rank_b = b.memory.strength * b.memory.confidence * recency_score(b.memory, now)
+
+            loser_id = b.memory.id if rank_a >= rank_b else a.memory.id
+            demoted.add(loser_id)
+
+    # Apply demotion: halve the score of the weaker contradicting memory
+    result = []
+    for sm in scored:
+        if sm.memory.id in demoted:
+            result.append(
+                ScoredMemory(
+                    memory=sm.memory,
+                    score=sm.score * 0.3,
+                    activation=sm.activation,
+                    components={**sm.components, "conflict_demoted": True},
+                )
+            )
+        else:
+            result.append(sm)
+
+    result.sort(key=lambda s: s.score, reverse=True)
+    return result

openmem/engine.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import math
+import time
+
+from .activation import spread_activation
+from .conflict import detect_and_resolve_conflicts
+from .models import Edge, Memory, ScoredMemory
+from .scoring import compete
+from .store import SQLiteStore
+
+# Rough token estimate: ~4 chars per token
+CHARS_PER_TOKEN = 4
+
+
+class MemoryEngine:
+    """Main entry point for the cognitive memory engine."""
+
+    def __init__(
+        self,
+        db_path: str = ":memory:",
+        max_hops: int = 2,
+        decay_per_hop: float = 0.5,
+        weights: dict[str, float] | None = None,
+    ):
+        self.store = SQLiteStore(db_path)
+        self.max_hops = max_hops
+        self.decay_per_hop = decay_per_hop
+        self.weights = weights
+
+    def add(
+        self,
+        text: str,
+        type: str = "fact",
+        entities: list[str] | None = None,
+        confidence: float = 1.0,
+        gist: str | None = None,
+    ) -> Memory:
+        """Add a new memory."""
+        now = time.time()
+        mem = Memory(
+            type=type,
+            text=text,
+            gist=gist,
+            entities=entities or [],
+            created_at=now,
+            updated_at=now,
+            confidence=confidence,
+        )
+        return self.store.add_memory(mem)
+
+    def link(
+        self,
+        source_id: str,
+        target_id: str,
+        rel_type: str = "mentions",
+        weight: float = 0.5,
+    ) -> Edge:
+        """Create an edge between two memories."""
+        edge = Edge(
+            source_id=source_id,
+            target_id=target_id,
+            rel_type=rel_type,
+            weight=weight,
+        )
+        return self.store.add_edge(edge)
+
+    def recall(
+        self,
+        query: str,
+        top_k: int = 5,
+        token_budget: int = 2000,
+    ) -> list[ScoredMemory]:
+        """Recall memories relevant to the query.
+
+        Pipeline: FTS5/BM25 → seed activation → spreading activation →
+        scoring competition → conflict resolution → token-budgeted output.
+        """
+        now = time.time()
+
+        # Step 1: Lexical trigger via BM25
+        bm25_hits = self.store.search_bm25(query, limit=top_k * 4)
+        if not bm25_hits:
+            return []
+
+        # Normalize BM25 scores to [0, 1] for seeding
+        max_score = max(s for _, s in bm25_hits) if bm25_hits else 1.0
+        if max_score == 0:
+            max_score = 1.0
+        seed_activations = {mid: score / max_score for mid, score in bm25_hits}
+
+        # Step 2: Spreading activation
+        activations = spread_activation(
+            seed_activations,
+            self.store,
+            max_hops=self.max_hops,
+            decay_per_hop=self.decay_per_hop,
+        )
+
+        # Step 3: Load all activated memories
+        memories = {}
+        for mid in activations:
+            mem = self.store.get_memory(mid)
+            if mem:
+                memories[mid] = mem
+
+        # Step 4: Competition scoring
+        scored = compete(activations, memories, weights=self.weights, now=now)
+
+        # Step 5: Conflict resolution
+        scored = detect_and_resolve_conflicts(scored, self.store, now=now)
+
+        # Step 6: Token-budget packing
+        char_budget = token_budget * CHARS_PER_TOKEN
+        packed: list[ScoredMemory] = []
+        used_chars = 0
+        for sm in scored:
+            text_len = len(sm.memory.text)
+            if used_chars + text_len > char_budget and packed:
+                break
+            packed.append(sm)
+            used_chars += text_len
+            if len(packed) >= top_k:
+                break
+
+        # Step 7: Update access stats for returned memories
+        for sm in packed:
+            self.store.update_access(sm.memory.id)
+
+        return packed
+
+    def reinforce(self, memory_id: str) -> None:
+        """Explicitly boost a memory's strength."""
+        mem = self.store.get_memory(memory_id)
+        if not mem:
+            return
+        mem.strength = min(1.0, mem.strength + 0.1)
+        mem.access_count += 1
+        mem.last_accessed = time.time()
+        self.store.update_memory(mem)
+
+    def supersede(self, old_id: str, new_id: str) -> None:
+        """Mark old memory as superseded and link to the new one."""
+        old = self.store.get_memory(old_id)
+        if old:
+            old.status = "superseded"
+            self.store.update_memory(old)
+        self.link(new_id, old_id, rel_type="same_as", weight=0.3)
+
+    def contradict(self, id_a: str, id_b: str) -> None:
+        """Mark two memories as contradicting each other."""
+        self.link(id_a, id_b, rel_type="contradicts", weight=0.8)
+
+    def decay_all(self) -> None:
+        """Run a decay pass over all memories, reducing strength by natural decay."""
+        now = time.time()
+        for mem in self.store.all_memories():
+            days = (now - mem.updated_at) / 86400.0
+            if days < 0.01:
+                continue
+            decay = math.exp(-0.01 * days)
+            mem.strength = max(0.0, min(1.0, mem.strength * decay))
+            self.store.update_memory(mem)
+
+    def stats(self) -> dict:
+        """Return summary statistics about the memory store."""
+        memories = self.store.all_memories()
+        edges = []
+        for m in memories:
+            edges.extend(self.store.get_edges(m.id))
+        # Deduplicate edges (they appear for both endpoints)
+        unique_edges = {e.id: e for e in edges}
+
+        strengths = [m.strength for m in memories]
+        return {
+            "memory_count": len(memories),
+            "edge_count": len(unique_edges),
+            "avg_strength": sum(strengths) / len(strengths) if strengths else 0,
+            "active_count": sum(1 for m in memories if m.status == "active"),
+            "superseded_count": sum(1 for m in memories if m.status == "superseded"),
+            "contradicted_count": sum(1 for m in memories if m.status == "contradicted"),
+        }

openmem/models.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Memory:
+    id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    type: str = "fact"  # decision | fact | preference | incident | plan | constraint
+    text: str = ""
+    gist: str | None = None
+    entities: list[str] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    strength: float = 1.0  # 0–1, decays over time, reinforced on access
+    confidence: float = 1.0  # 0–1, set at creation
+    access_count: int = 0
+    last_accessed: float | None = None
+    status: str = "active"  # active | superseded | contradicted
+
+
+@dataclass
+class Edge:
+    id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    source_id: str = ""
+    target_id: str = ""
+    rel_type: str = "mentions"  # mentions | supports | contradicts | depends_on | same_as
+    weight: float = 0.5  # 0–1
+    created_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class ScoredMemory:
+    memory: Memory
+    score: float  # final competition score
+    activation: float  # raw activation (seed + spread)
+    components: dict = field(default_factory=dict)
+    # breakdown: {activation, recency, strength, confidence}

openmem/scoring.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import math
+import time
+
+from .models import Memory, ScoredMemory
+
+# Recency decay: half-life ~14 days
+LAMBDA_RECENCY = 0.05
+# Strength natural decay rate
+ALPHA_DECAY = 0.01
+# Reinforcement factor
+BETA_REINFORCE = 0.1
+
+# Default competition weights
+DEFAULT_WEIGHTS = {
+    "activation": 0.5,
+    "recency": 0.2,
+    "strength": 0.2,
+    "confidence": 0.1,
+}
+
+# Status penalties
+STATUS_PENALTY = {
+    "active": 1.0,
+    "superseded": 0.5,
+    "contradicted": 0.3,
+}
+
+
+def recency_score(memory: Memory, now: float | None = None) -> float:
+    """Exponential recency decay. Uses last_accessed if available, else created_at."""
+    if now is None:
+        now = time.time()
+    t_ref = memory.last_accessed if memory.last_accessed is not None else memory.created_at
+    days_elapsed = (now - t_ref) / 86400.0
+    return math.exp(-LAMBDA_RECENCY * days_elapsed)
+
+
+def strength_score(memory: Memory, now: float | None = None) -> float:
+    """Strength with reinforcement and natural decay, clamped to [0, 1]."""
+    if now is None:
+        now = time.time()
+    days_since_creation = (now - memory.created_at) / 86400.0
+    raw = memory.strength * (1 + memory.access_count) ** BETA_REINFORCE * math.exp(
+        -ALPHA_DECAY * days_since_creation
+    )
+    return max(0.0, min(1.0, raw))
+
+
+def _normalize(values: dict[str, float]) -> dict[str, float]:
+    """Min-max normalize to [0, 1]. If all values are equal, return 1.0 for all."""
+    if not values:
+        return {}
+    max_v = max(values.values())
+    min_v = min(values.values())
+    span = max_v - min_v
+    if span == 0:
+        return {k: 1.0 for k in values}
+    return {k: (v - min_v) / span for k, v in values.items()}
+
+
+def compete(
+    activations: dict[str, float],
+    memories: dict[str, Memory],
+    weights: dict[str, float] | None = None,
+    now: float | None = None,
+) -> list[ScoredMemory]:
+    """Score and rank activated memories using the competition model.
+
+    Returns ScoredMemory list sorted by descending score.
+    """
+    if now is None:
+        now = time.time()
+    w = weights or DEFAULT_WEIGHTS
+
+    if not activations:
+        return []
+
+    # Compute raw component scores
+    raw_activation = {mid: activations[mid] for mid in activations if mid in memories}
+    raw_recency = {mid: recency_score(memories[mid], now) for mid in raw_activation}
+    raw_strength = {mid: strength_score(memories[mid], now) for mid in raw_activation}
+
+    # Normalize activation and strength
+    norm_activation = _normalize(raw_activation)
+    norm_strength = _normalize(raw_strength)
+
+    results = []
+    for mid in raw_activation:
+        mem = memories[mid]
+        components = {
+            "activation": norm_activation[mid],
+            "recency": raw_recency[mid],
+            "strength": norm_strength[mid],
+            "confidence": mem.confidence,
+        }
+        score = (
+            w["activation"] * components["activation"]
+            + w["recency"] * components["recency"]
+            + w["strength"] * components["strength"]
+            + w["confidence"] * components["confidence"]
+        )
+        # Apply status penalty
+        penalty = STATUS_PENALTY.get(mem.status, 1.0)
+        score *= penalty
+
+        results.append(
+            ScoredMemory(
+                memory=mem,
+                score=score,
+                activation=activations[mid],
+                components=components,
+            )
+        )
+
+    results.sort(key=lambda s: s.score, reverse=True)
+    return results

openmem/store.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from typing import Optional
+
+from .models import Edge, Memory
+
+
+class SQLiteStore:
+    def __init__(self, db_path: str = ":memory:"):
+        self.conn = sqlite3.connect(db_path)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.execute("PRAGMA journal_mode=WAL")
+        self.conn.execute("PRAGMA foreign_keys=ON")
+        self._create_tables()
+
+    def _create_tables(self) -> None:
+        self.conn.executescript("""
+            CREATE TABLE IF NOT EXISTS memories (
+                id TEXT PRIMARY KEY,
+                type TEXT NOT NULL DEFAULT 'fact',
+                text TEXT NOT NULL,
+                gist TEXT,
+                entities TEXT NOT NULL DEFAULT '[]',
+                created_at REAL NOT NULL,
+                updated_at REAL NOT NULL,
+                strength REAL NOT NULL DEFAULT 1.0,
+                confidence REAL NOT NULL DEFAULT 1.0,
+                access_count INTEGER NOT NULL DEFAULT 0,
+                last_accessed REAL,
+                status TEXT NOT NULL DEFAULT 'active'
+            );
+
+            CREATE TABLE IF NOT EXISTS edges (
+                id TEXT PRIMARY KEY,
+                source_id TEXT NOT NULL,
+                target_id TEXT NOT NULL,
+                rel_type TEXT NOT NULL DEFAULT 'mentions',
+                weight REAL NOT NULL DEFAULT 0.5,
+                created_at REAL NOT NULL,
+                FOREIGN KEY (source_id) REFERENCES memories(id),
+                FOREIGN KEY (target_id) REFERENCES memories(id)
+            );
+
+            CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+                id UNINDEXED,
+                text,
+                gist,
+                entities,
+                content='memories',
+                content_rowid='rowid'
+            );
+
+            -- Triggers to keep FTS in sync
+            CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+                INSERT INTO memories_fts(rowid, id, text, gist, entities)
+                VALUES (new.rowid, new.id, new.text, new.gist, new.entities);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+                INSERT INTO memories_fts(memories_fts, rowid, id, text, gist, entities)
+                VALUES ('delete', old.rowid, old.id, old.text, old.gist, old.entities);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+                INSERT INTO memories_fts(memories_fts, rowid, id, text, gist, entities)
+                VALUES ('delete', old.rowid, old.id, old.text, old.gist, old.entities);
+                INSERT INTO memories_fts(rowid, id, text, gist, entities)
+                VALUES (new.rowid, new.id, new.text, new.gist, new.entities);
+            END;
+        """)
+        self.conn.commit()
+
+    def _row_to_memory(self, row: sqlite3.Row) -> Memory:
+        return Memory(
+            id=row["id"],
+            type=row["type"],
+            text=row["text"],
+            gist=row["gist"],
+            entities=json.loads(row["entities"]),
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            strength=row["strength"],
+            confidence=row["confidence"],
+            access_count=row["access_count"],
+            last_accessed=row["last_accessed"],
+            status=row["status"],
+        )
+
+    def _row_to_edge(self, row: sqlite3.Row) -> Edge:
+        return Edge(
+            id=row["id"],
+            source_id=row["source_id"],
+            target_id=row["target_id"],
+            rel_type=row["rel_type"],
+            weight=row["weight"],
+            created_at=row["created_at"],
+        )
+
+    def add_memory(self, memory: Memory) -> Memory:
+        entities_json = json.dumps(memory.entities)
+        self.conn.execute(
+            """INSERT INTO memories (id, type, text, gist, entities, created_at,
+               updated_at, strength, confidence, access_count, last_accessed, status)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                memory.id, memory.type, memory.text, memory.gist, entities_json,
+                memory.created_at, memory.updated_at, memory.strength,
+                memory.confidence, memory.access_count, memory.last_accessed,
+                memory.status,
+            ),
+        )
+        self.conn.commit()
+        return memory
+
+    def add_edge(self, edge: Edge) -> Edge:
+        self.conn.execute(
+            """INSERT INTO edges (id, source_id, target_id, rel_type, weight, created_at)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (edge.id, edge.source_id, edge.target_id, edge.rel_type,
+             edge.weight, edge.created_at),
+        )
+        self.conn.commit()
+        return edge
+
+    def get_memory(self, memory_id: str) -> Optional[Memory]:
+        row = self.conn.execute(
+            "SELECT * FROM memories WHERE id = ?", (memory_id,)
+        ).fetchone()
+        return self._row_to_memory(row) if row else None
+
+    def get_edges(self, memory_id: str) -> list[Edge]:
+        rows = self.conn.execute(
+            "SELECT * FROM edges WHERE source_id = ? OR target_id = ?",
+            (memory_id, memory_id),
+        ).fetchall()
+        return [self._row_to_edge(r) for r in rows]
+
+    def get_neighbors(self, memory_id: str) -> list[tuple[Edge, Memory]]:
+        edges = self.get_edges(memory_id)
+        result = []
+        for edge in edges:
+            neighbor_id = edge.target_id if edge.source_id == memory_id else edge.source_id
+            neighbor = self.get_memory(neighbor_id)
+            if neighbor:
+                result.append((edge, neighbor))
+        return result
+
+    def search_bm25(self, query: str, limit: int = 20) -> list[tuple[str, float]]:
+        """FTS5 MATCH with BM25 ranking. Returns (memory_id, bm25_score) pairs."""
+        # Escape special FTS5 characters in the query
+        safe_query = self._escape_fts_query(query)
+        if not safe_query.strip():
+            return []
+        rows = self.conn.execute(
+            """SELECT id, bm25(memories_fts) as rank
+               FROM memories_fts
+               WHERE memories_fts MATCH ?
+               ORDER BY rank
+               LIMIT ?""",
+            (safe_query, limit),
+        ).fetchall()
+        # bm25() returns negative scores (lower = better match), negate for positive scores
+        return [(row["id"], -row["rank"]) for row in rows]
+
+    def _escape_fts_query(self, query: str) -> str:
+        """Turn a raw user query into a safe FTS5 query by quoting each token."""
+        tokens = query.split()
+        if not tokens:
+            return ""
+        # Quote each token to avoid FTS5 syntax errors from special chars
+        quoted = ['"' + t.replace('"', '""') + '"' for t in tokens]
+        return " OR ".join(quoted)
+
+    def update_access(self, memory_id: str) -> None:
+        now = time.time()
+        self.conn.execute(
+            """UPDATE memories SET access_count = access_count + 1,
+               last_accessed = ?, updated_at = ? WHERE id = ?""",
+            (now, now, memory_id),
+        )
+        self.conn.commit()
+
+    def update_memory(self, memory: Memory) -> None:
+        entities_json = json.dumps(memory.entities)
+        self.conn.execute(
+            """UPDATE memories SET type=?, text=?, gist=?, entities=?,
+               updated_at=?, strength=?, confidence=?, access_count=?,
+               last_accessed=?, status=? WHERE id=?""",
+            (
+                memory.type, memory.text, memory.gist, entities_json,
+                memory.updated_at, memory.strength, memory.confidence,
+                memory.access_count, memory.last_accessed, memory.status,
+                memory.id,
+            ),
+        )
+        self.conn.commit()
+
+    def all_memories(self) -> list[Memory]:
+        rows = self.conn.execute("SELECT * FROM memories").fetchall()
+        return [self._row_to_memory(r) for r in rows]
+
+    def close(self) -> None:
+        self.conn.close()

openmem_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: openmem-engine
+Version: 0.1.0
+Summary: Cognitive memory engine for AI agents — human-inspired retrieval via activation, competition, and reconstruction
+Project-URL: Homepage, https://github.com/dunkinfrunkin/OpenMem
+Project-URL: Documentation, https://dunkinfrunkin.github.io/OpenMem/
+Project-URL: Repository, https://github.com/dunkinfrunkin/OpenMem
+Project-URL: Issues, https://github.com/dunkinfrunkin/OpenMem/issues
+Author: OpenMem
+License-Expression: MIT
+Keywords: agents,ai,cognitive,llm,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# OpenMem
+
+Deterministic memory engine for AI agents. Retrieves context via BM25 lexical search, graph-based spreading activation, and human-inspired competition scoring. SQLite-backed, zero dependencies.
+
+## How it works
+
+```
+Query → FTS5/BM25 (lexical trigger)
+      → Seed Activation
+      → Spreading Activation (graph edges, max 2 hops)
+      → Recency + Strength + Confidence weighting
+      → Competition (score-based ranking)
+      → Context Pack (token-budgeted output)
+```
+
+No vectors, no embeddings, no LLM in the retrieval loop. The LLM is the consumer, not the retriever.
+
+## Install
+
+```bash
+pip install openmem-engine
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/yourorg/openmem.git
+cd openmem
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from openmem import MemoryEngine
+
+engine = MemoryEngine()  # in-memory, or MemoryEngine("memories.db") for persistence
+
+# Store memories
+m1 = engine.add("We chose SQLite over Postgres for simplicity", type="decision", entities=["SQLite", "Postgres"])
+m2 = engine.add("Postgres has better concurrent write support", type="fact", entities=["Postgres"])
+
+# Link related memories
+engine.link(m1.id, m2.id, "supports")
+
+# Recall
+results = engine.recall("Why did we pick SQLite?")
+for r in results:
+    print(f"{r.score:.3f} | {r.memory.text}")
+# 0.800 | We chose SQLite over Postgres for simplicity
+# 0.500 | Postgres has better concurrent write support
+```
+
+## Claude Code plugin
+
+Install OpenMem as a Claude Code plugin to get persistent memory across sessions:
+
+```bash
+pip install openmem-engine "mcp>=1.0"
+claude plugin install --path ./plugin
+```
+
+Once installed, you get three slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/openmem:recall` | Recall memories relevant to the current conversation |
+| `/openmem:store` | Store key facts, decisions, and preferences from the conversation |
+| `/openmem:status` | Show memory store statistics |
+
+The plugin also registers an MCP server with 7 tools (`memory_store`, `memory_recall`, `memory_link`, `memory_reinforce`, `memory_supersede`, `memory_contradict`, `memory_stats`) that Claude can call automatically.
+
+Memories persist in `~/.openmem/memories.db` by default (override with the `OPENMEM_DB` env var).
+
+## Usage with an LLM agent
+
+```python
+engine = MemoryEngine("project.db")
+
+# Agent stores what it learns
+engine.add("User prefers TypeScript over JavaScript", type="preference", entities=["TypeScript", "JavaScript"])
+engine.add("Auth system uses JWT with 24h expiry", type="decision", entities=["JWT", "auth"])
+engine.add("The /api/users endpoint returns 500 on empty payload", type="incident", entities=["/api/users"])
+
+# Before each LLM call, recall relevant context
+results = engine.recall("set up authentication", top_k=5, token_budget=2000)
+context = "\n".join(r.memory.text for r in results)
+
+prompt = f"""Relevant context from previous work:
+{context}
+
+User request: {user_message}"""
+```
+
+## API
+
+### `MemoryEngine(db_path=":memory:", **config)`
+
+| Method | Description |
+|--------|-------------|
+| `add(text, type="fact", entities=None, confidence=1.0, gist=None)` | Store a memory |
+| `link(source_id, target_id, rel_type, weight=0.5)` | Create an edge between memories |
+| `recall(query, top_k=5, token_budget=2000)` | Retrieve relevant memories |
+| `reinforce(memory_id)` | Boost a memory's strength |
+| `supersede(old_id, new_id)` | Mark a memory as outdated |
+| `contradict(id_a, id_b)` | Flag two memories as contradicting |
+| `decay_all()` | Run decay pass over all memories |
+| `stats()` | Get summary statistics |
+
+### Memory types
+
+`fact` · `decision` · `preference` · `incident` · `plan` · `constraint`
+
+### Edge types
+
+`mentions` · `supports` · `contradicts` · `depends_on` · `same_as`
+
+## Retrieval model
+
+**Recency** — Exponential decay with ~14-day half-life. Recently accessed memories surface first.
+
+**Strength** — Reinforced on access, decays naturally over time. Frequently recalled memories persist.
+
+**Spreading activation** — Memories linked by edges activate their neighbors. A query hitting one memory pulls in related context up to 2 hops away.
+
+**Competition** — Final score combines activation (50%), recency (20%), strength (20%), and confidence (10%). Superseded memories are penalized 50%, contradicted ones 70%.
+
+**Conflict resolution** — When two contradicting memories both activate, the weaker one (by strength × confidence × recency) gets demoted.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## License
+
+MIT

openmem_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+openmem/__init__.py,sha256=jBfOWsajHfAKbAk3JQnv9UK4gE569lu9VHY2U4U8qzw,142
+openmem/activation.py,sha256=FPcOG-nWAC32WpFwT_QSIwRdk_NS1gB07oxoPQ4fdRA,1134
+openmem/conflict.py,sha256=t06c_ChuDv2VNrVLH_1j70E0sXJep_VInzwgVmlMdGU,1927
+openmem/engine.py,sha256=ubb8jczkl6K_4Wg2t_97bXfMWjqDfHWlqWmBbkvnZ4w,5902
+openmem/models.py,sha256=tcWFqfFTHOfsa_eG-b1CcNKaplU1IUlK9KWZ72JaCMw,1330
+openmem/scoring.py,sha256=yeZQyHM7WQg4FrqitOUPrcuTqeXLhS47bImR2EKAbtU,3518
+openmem/store.py,sha256=WIhtSRQD7K7kAU0GXc7cPbZyEIbSJXZiENMUGmwIg14,8057
+openmem_engine-0.1.0.dist-info/METADATA,sha256=ojampS4bUOsLSkxhGDQzM4Pe2AQyNPJBHtOBc6JYwwA,5756
+openmem_engine-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openmem_engine-0.1.0.dist-info/RECORD,,

openmem_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any