openmem-engine 0.1.0__tar.gz

openmem_engine-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "web/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: web/build
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

openmem_engine-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openmem_engine-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+web/node_modules/
+web/build/
+web/.docusaurus/

openmem_engine-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "openmem",
+  "version": "0.1.0",
+  "description": "Persistent memory for Claude Code across sessions",
+  "author": { "name": "OpenMem" },
+  "repository": "https://github.com/yourorg/openmem",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}

openmem_engine-0.1.0/plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "openmem": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/openmem_server.py"],
+      "env": {}
+    }
+  }
+}

openmem_engine-0.1.0/plugin/servers/formatting.py

@@ -0,0 +1,69 @@
+"""Output formatting helpers for the OpenMem MCP server."""
+
+from __future__ import annotations
+
+from openmem.models import Memory, ScoredMemory
+
+
+def format_memory(mem: Memory) -> str:
+    """Format a single Memory as structured plain text."""
+    lines = [
+        f"[{mem.id}]",
+        f"  type: {mem.type}",
+        f"  status: {mem.status}",
+        f"  text: {mem.text}",
+    ]
+    if mem.gist:
+        lines.append(f"  gist: {mem.gist}")
+    if mem.entities:
+        lines.append(f"  entities: {', '.join(mem.entities)}")
+    lines.append(f"  strength: {mem.strength:.2f}")
+    lines.append(f"  confidence: {mem.confidence:.2f}")
+    lines.append(f"  access_count: {mem.access_count}")
+    return "\n".join(lines)
+
+
+def format_scored_memory(sm: ScoredMemory) -> str:
+    """Format a ScoredMemory with its score and components."""
+    lines = [
+        f"[{sm.memory.id}]",
+        f"  score: {sm.score:.4f}",
+        f"  type: {sm.memory.type}",
+        f"  status: {sm.memory.status}",
+        f"  text: {sm.memory.text}",
+    ]
+    if sm.memory.gist:
+        lines.append(f"  gist: {sm.memory.gist}")
+    if sm.memory.entities:
+        lines.append(f"  entities: {', '.join(sm.memory.entities)}")
+    lines.append(f"  strength: {sm.memory.strength:.2f}")
+    lines.append(f"  confidence: {sm.memory.confidence:.2f}")
+    if sm.components:
+        parts = ", ".join(f"{k}={v:.3f}" for k, v in sm.components.items())
+        lines.append(f"  components: {parts}")
+    return "\n".join(lines)
+
+
+def format_recall_results(results: list[ScoredMemory]) -> str:
+    """Format a list of recall results."""
+    if not results:
+        return "No memories found."
+    sections = [f"Found {len(results)} memories:\n"]
+    for i, sm in enumerate(results, 1):
+        sections.append(f"--- Result {i} ---")
+        sections.append(format_scored_memory(sm))
+        sections.append("")
+    return "\n".join(sections)
+
+
+def format_stats(stats: dict) -> str:
+    """Format memory store statistics."""
+    return "\n".join([
+        "Memory Store Statistics:",
+        f"  Total memories: {stats['memory_count']}",
+        f"  Active: {stats['active_count']}",
+        f"  Superseded: {stats['superseded_count']}",
+        f"  Contradicted: {stats['contradicted_count']}",
+        f"  Total edges: {stats['edge_count']}",
+        f"  Average strength: {stats['avg_strength']:.2f}",
+    ])

openmem_engine-0.1.0/plugin/servers/openmem_server.py

@@ -0,0 +1,209 @@
+"""OpenMem MCP server — persistent memory tools for Claude Code.
+
+Exposes 7 tools via FastMCP (stdio transport):
+  memory_store, memory_recall, memory_link,
+  memory_reinforce, memory_supersede, memory_contradict,
+  memory_stats
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+# Ensure openmem is importable — handle both installed and dev setups
+_repo_root = Path(__file__).resolve().parent.parent.parent
+_src_dir = _repo_root / "src"
+if _src_dir.is_dir() and str(_src_dir) not in sys.path:
+    sys.path.insert(0, str(_src_dir))
+
+from openmem import MemoryEngine  # noqa: E402
+
+from formatting import format_memory, format_recall_results, format_stats  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Initialisation
+# ---------------------------------------------------------------------------
+
+DEFAULT_DB = os.path.join(Path.home(), ".openmem", "memories.db")
+db_path = os.environ.get("OPENMEM_DB", DEFAULT_DB)
+
+# Ensure the DB directory exists
+os.makedirs(os.path.dirname(db_path), exist_ok=True)
+
+engine = MemoryEngine(db_path=db_path)
+
+# Run decay pass on startup so stale memories lose strength naturally
+engine.decay_all()
+
+mcp = FastMCP(
+    "openmem",
+    description="Persistent cognitive memory for Claude Code",
+)
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+
+@mcp.tool()
+def memory_store(
+    text: str,
+    type: str = "fact",
+    entities: list[str] | None = None,
+    confidence: float = 1.0,
+    gist: str | None = None,
+) -> str:
+    """Store a new memory.
+
+    Args:
+        text: The content of the memory to store.
+        type: Memory type — one of: fact, decision, preference, incident, plan, constraint.
+        entities: Key entities mentioned (project names, people, technologies).
+        confidence: How certain this memory is, from 0.0 to 1.0.
+        gist: Optional one-line summary for quick retrieval.
+
+    Returns:
+        Confirmation with the stored memory's ID and details.
+    """
+    mem = engine.add(
+        text=text,
+        type=type,
+        entities=entities,
+        confidence=confidence,
+        gist=gist,
+    )
+    return f"Stored memory:\n{format_memory(mem)}"
+
+
+@mcp.tool()
+def memory_recall(
+    query: str,
+    top_k: int = 5,
+    token_budget: int = 2000,
+) -> str:
+    """Recall memories relevant to a query.
+
+    Uses BM25 lexical search, spreading activation through the memory graph,
+    competition scoring, and conflict resolution to find the most relevant memories.
+
+    Args:
+        query: The search query — what you want to remember.
+        top_k: Maximum number of memories to return.
+        token_budget: Approximate token budget for returned memories.
+
+    Returns:
+        Formatted list of matching memories ranked by relevance.
+    """
+    results = engine.recall(query=query, top_k=top_k, token_budget=token_budget)
+    return format_recall_results(results)
+
+
+@mcp.tool()
+def memory_link(
+    source_id: str,
+    target_id: str,
+    rel_type: str = "mentions",
+    weight: float = 0.5,
+) -> str:
+    """Create a relationship between two memories.
+
+    Links enable spreading activation — related memories boost each other during recall.
+
+    Args:
+        source_id: ID of the source memory.
+        target_id: ID of the target memory.
+        rel_type: Relationship type — one of: mentions, supports, contradicts, depends_on, same_as.
+        weight: Edge weight from 0.0 to 1.0, controls activation spread strength.
+
+    Returns:
+        Confirmation with the edge details.
+    """
+    edge = engine.link(
+        source_id=source_id,
+        target_id=target_id,
+        rel_type=rel_type,
+        weight=weight,
+    )
+    return f"Linked memories:\n  edge_id: {edge.id}\n  {source_id} --[{rel_type}, w={weight}]--> {target_id}"
+
+
+@mcp.tool()
+def memory_reinforce(memory_id: str) -> str:
+    """Reinforce a memory, boosting its strength.
+
+    Call this when a memory proves useful — it increases strength by 0.1 (up to 1.0)
+    and updates access stats. Reinforced memories rank higher in future recalls.
+
+    Args:
+        memory_id: ID of the memory to reinforce.
+
+    Returns:
+        Confirmation of the reinforcement.
+    """
+    engine.reinforce(memory_id)
+    mem = engine.store.get_memory(memory_id)
+    if mem:
+        return f"Reinforced memory:\n{format_memory(mem)}"
+    return f"Memory {memory_id} not found."
+
+
+@mcp.tool()
+def memory_supersede(old_id: str, new_id: str) -> str:
+    """Mark an old memory as superseded by a newer one.
+
+    The old memory receives a 50% score penalty in future recalls.
+    A 'same_as' link is created from the new memory to the old one.
+
+    Args:
+        old_id: ID of the outdated memory.
+        new_id: ID of the replacement memory.
+
+    Returns:
+        Confirmation of the supersession.
+    """
+    engine.supersede(old_id=old_id, new_id=new_id)
+    return f"Memory {old_id} superseded by {new_id}."
+
+
+@mcp.tool()
+def memory_contradict(id_a: str, id_b: str) -> str:
+    """Mark two memories as contradicting each other.
+
+    Creates a 'contradicts' edge. During recall, the weaker memory
+    (by strength x confidence x recency) is demoted to 30% of its score.
+
+    Args:
+        id_a: ID of the first memory.
+        id_b: ID of the second memory.
+
+    Returns:
+        Confirmation of the contradiction.
+    """
+    engine.contradict(id_a=id_a, id_b=id_b)
+    return f"Memories {id_a} and {id_b} marked as contradicting."
+
+
+@mcp.tool()
+def memory_stats() -> str:
+    """Get summary statistics about the memory store.
+
+    Returns counts of total, active, superseded, and contradicted memories,
+    the number of edges, and average memory strength.
+
+    Returns:
+        Formatted statistics summary.
+    """
+    stats = engine.stats()
+    return format_stats(stats)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")