coremem 0.1.0__py3-none-any.whl

coremem/__init__.py

@@ -0,0 +1,21 @@
+"""coremem — Zero-LLM memory for AI agents.
+
+Dual-backend architecture:
+  - ChromaBackend: Pure ChromaDB (baseline, 95%+ LongMemEval target)
+  - HybridBackend: HybridDB (SQLite+FTS5+ChromaDB, >95% target)
+
+Usage:
+    from coremem import MemoryCore
+    from coremem.backends.chroma import ChromaBackend
+
+    core = MemoryCore(backend=ChromaBackend(path="./memory"))
+    results = core.search("How many model kits?")
+    context = core.wakeup(user_id="alice")
+    core.ingest("user", "I built a Spitfire model kit")
+"""
+
+from coremem.core import MemoryCore
+from coremem.heuristics import SearchHeuristics
+from coremem.types import Memory, SearchQuery, SearchResult
+
+__all__ = ["MemoryCore", "Memory", "SearchResult", "SearchQuery", "SearchHeuristics"]

coremem/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Backend implementations for coremem."""
+
+from coremem.backends.base import StoreBackend
+
+__all__ = ["StoreBackend"]

coremem/backends/base.py

@@ -0,0 +1,44 @@
+"""Abstract backend interface."""
+
+from abc import ABC, abstractmethod
+
+from coremem.types import Memory, SearchQuery, SearchResult
+
+
+class StoreBackend(ABC):
+    """Abstract memory storage and retrieval backend.
+
+    Implementations:
+      - ChromaBackend: pure ChromaDB
+      - HybridBackend: HybridDB (SQLite + FTS5 + ChromaDB)
+    """
+
+    @abstractmethod
+    def ingest(self, memory: Memory) -> str:
+        """Store a memory. Returns the storage ID."""
+        ...
+
+    @abstractmethod
+    def ingest_batch(self, memories: list[Memory]) -> list[str]:
+        """Store multiple memories in one batch. Returns storage IDs."""
+        ...
+
+    @abstractmethod
+    def search(self, query: SearchQuery) -> list[SearchResult]:
+        """Search for memories by query text."""
+        ...
+
+    @abstractmethod
+    def get_recent(self, limit: int = 10) -> list[Memory]:
+        """Return most recently stored memories."""
+        ...
+
+    @abstractmethod
+    def count(self) -> int:
+        """Return total number of stored memories."""
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Delete all memories."""
+        ...

coremem/backends/chroma.py

@@ -0,0 +1,130 @@
+"""Pure ChromaDB backend — baseline, zero LLM."""
+
+from coremem.backends.base import StoreBackend
+from coremem.types import Memory, SearchQuery, SearchResult
+
+
+class ChromaBackend(StoreBackend):
+    """ChromaDB-only backend for semantic search.
+
+    Stores verbatim text and retrieves via cosine similarity.
+    Metadata filtering supports wing/room scoping (optional).
+    """
+
+    def __init__(self, path: str):
+        try:
+            import chromadb
+        except ImportError:
+            raise ImportError(
+                "chromadb is required for ChromaBackend. "
+                "Install with: pip install chromadb"
+            )
+        self._client = chromadb.PersistentClient(path=path)
+        self._collection = self._client.get_or_create_collection(
+            name="mempalace_drawers",
+            metadata={"hnsw:space": "cosine"},
+        )
+
+    def ingest(self, memory: Memory) -> str:
+        ids = self.ingest_batch([memory])
+        return ids[0] if ids else ""
+
+    def ingest_batch(self, memories: list[Memory]) -> list[str]:
+        import uuid
+
+        if not memories:
+            return []
+
+        ids = [m.id or str(uuid.uuid4())[:12] for m in memories]
+        documents = [m.content for m in memories]
+        metadatas = [
+            {
+                "role": m.role,
+                "session_id": m.session_id or "",
+                **({"ts": m.ts.isoformat()} if m.ts else {}),
+            }
+            for m in memories
+        ]
+        self._collection.add(ids=ids, documents=documents, metadatas=metadatas)
+        return ids
+
+    def ingest_batch(self, memories: list[Memory]) -> list[str]:
+        import uuid
+        if not memories:
+            return []
+        ids = [m.id or str(uuid.uuid4())[:12] for m in memories]
+        documents = [m.content for m in memories]
+        metadatas = [
+            {
+                "role": m.role,
+                "session_id": m.session_id or "",
+                **({"ts": m.ts.isoformat()} if m.ts else {}),
+            }
+            for m in memories
+        ]
+        self._collection.add(ids=ids, documents=documents, metadatas=metadatas)
+        return ids
+
+    def search(self, query: SearchQuery) -> list[SearchResult]:
+        where = {}
+        if query.wing:
+            where["wing"] = query.wing
+        if query.room:
+            where["room"] = query.room
+
+        kwargs = {"n_results": query.limit}
+        if where:
+            kwargs["where"] = where
+
+        results = self._collection.query(
+            query_texts=[query.text],
+            include=["documents", "metadatas", "distances"],
+            **kwargs,
+        )
+
+        search_results = []
+        if results["ids"] and results["ids"][0]:
+            for i, mid in enumerate(results["ids"][0]):
+                doc = results["documents"][0][i] if results["documents"] else ""
+                meta = results["metadatas"][0][i] if results["metadatas"] else {}
+                dist = results["distances"][0][i] if results["distances"] else 1.0
+                score = 1.0 - dist
+
+                memory = Memory(
+                    id=mid,
+                    content=doc,
+                    role=meta.get("role", "user"),
+                    session_id=meta.get("session_id"),
+                    score=score,
+                )
+                search_results.append(SearchResult(memory=memory, score=score, source="semantic"))
+
+        return search_results
+
+    def get_recent(self, limit: int = 10) -> list[Memory]:
+        results = self._collection.get(
+            limit=limit,
+            include=["documents", "metadatas"],
+        )
+        memories = []
+        if results["ids"]:
+            for i, mid in enumerate(results["ids"]):
+                doc = results["documents"][i] if results["documents"] else ""
+                meta = results["metadatas"][i] if results["metadatas"] else {}
+                memories.append(Memory(
+                    id=mid,
+                    content=doc,
+                    role=meta.get("role", "user"),
+                    session_id=meta.get("session_id"),
+                ))
+        return memories
+
+    def count(self) -> int:
+        return self._collection.count()
+
+    def clear(self) -> None:
+        self._client.delete_collection("mempalace_drawers")
+        self._collection = self._client.get_or_create_collection(
+            name="mempalace_drawers",
+            metadata={"hnsw:space": "cosine"},
+        )

coremem/backends/hybrid.py

@@ -0,0 +1,185 @@
+"""HybridDB backend — SQLite + FTS5 + ChromaDB via hybriddb.
+
+Leverages all three HybridDB layers:
+  - SQLite: structured storage, metadata, timestamps
+  - FTS5: exact keyword/term matching with BM25-like scoring
+  - ChromaDB: semantic similarity via all-MiniLM-L6-v2 embeddings
+
+The fused ranking formula:
+  fused_score = semantic_score * (1 + fts_weight * keyword_overlap)
+"""
+
+import json
+from datetime import datetime
+
+from coremem.backends.base import StoreBackend
+from coremem.types import Memory, SearchQuery, SearchResult
+
+
+class HybridBackend(StoreBackend):
+    """HybridDB backend combining semantic + keyword + structured search.
+
+    Ingestion writes to SQLite via HybridDB's journal. The journal
+    automatically embeds and indexes into ChromaDB. FTS5 handles
+    keyword matching during retrieval. Results are fused via
+    semantic * (1 + fts_weight * keyword_overlap).
+    """
+
+    def __init__(self, path: str):
+        from hybriddb import HybridDB
+
+        self._path = path
+        self._db = HybridDB(path=path)
+        self._ensure_tables()
+
+    def _ensure_tables(self) -> None:
+        try:
+            self._db.create_table(
+                "messages",
+                {
+                    "id": "TEXT PRIMARY KEY",
+                    "content": "LONGTEXT",
+                    "role": "TEXT",
+                    "metadata": "TEXT",
+                    "ts": "TEXT",
+                },
+            )
+        except Exception:
+            pass
+
+    def ingest(self, memory: Memory) -> str:
+        ids = self.ingest_batch([memory])
+        return ids[0] if ids else ""
+
+    def ingest_batch(self, memories: list[Memory]) -> list[str]:
+        import uuid
+
+        if not memories:
+            return []
+        rows = []
+        ids = []
+        for m in memories:
+            mid = str(uuid.uuid4())[:12]
+            ids.append(mid)
+            metadata = {
+                "role": m.role,
+                "session_id": m.session_id or "",
+                "ts": m.ts.isoformat() if m.ts else datetime.now().isoformat(),
+            }
+            rows.append({
+                "id": mid,
+                "content": m.content,
+                "role": m.role,
+                "metadata": json.dumps(metadata),
+                "ts": m.ts.isoformat() if m.ts else datetime.now().isoformat(),
+            })
+        self._db.insert_batch("messages", rows)
+        return ids
+
+    def search(self, query: SearchQuery) -> list[SearchResult]:
+        import sys
+        db_module = sys.modules.get(type(self._db).__module__)
+        search_mode = getattr(db_module, "SearchMode", None) if db_module else None
+
+        fetch_limit = query.limit * 3
+        fts_weight = 0.5
+
+        kwargs = {
+            "table": "messages",
+            "column": "content",
+            "query": query.text,
+            "limit": fetch_limit,
+        }
+        if search_mode is not None:
+            kwargs["mode"] = search_mode.HYBRID
+            kwargs["fts_weight"] = fts_weight
+            kwargs["recency_weight"] = 0.3
+            kwargs["recency_column"] = "ts"
+
+        raw_rows = self._db.search(**kwargs)
+
+        seen_sessions: set[str] = set()
+        results = []
+        for row in raw_rows:
+            rid = row.get("id", "")
+            content = row.get("content", "")
+            score = float(row.get("_score", 0.0))
+            ts_str = row.get("ts", "")
+            role = row.get("role", "")
+
+            meta_dict = {}
+            raw_meta = row.get("metadata")
+            if raw_meta:
+                if isinstance(raw_meta, str):
+                    try:
+                        meta_dict = json.loads(raw_meta)
+                    except (json.JSONDecodeError, TypeError):
+                        pass
+                elif isinstance(raw_meta, dict):
+                    meta_dict = raw_meta
+
+            sid = meta_dict.get("session_id", "")
+            ws_id = meta_dict.get("workspace_id", "")
+            if sid and sid in seen_sessions:
+                continue
+            if sid:
+                seen_sessions.add(sid)
+
+            ts = None
+            if ts_str:
+                try:
+                    ts = datetime.fromisoformat(ts_str)
+                except (ValueError, TypeError):
+                    pass
+
+            results.append(SearchResult(
+                    memory=Memory(
+                        id=str(rid),
+                        content=content,
+                        role=role,
+                        ts=ts,
+                        session_id=sid or None,
+                        workspace_id=ws_id or None,
+                        score=score,
+                    ),
+                score=score,
+                source="hybrid",
+            ))
+
+            if len(results) >= query.limit:
+                break
+
+        return results
+
+    def get_recent(self, limit: int = 10) -> list[Memory]:
+        try:
+            rows = self._db.search(
+                table="messages",
+                column="content",
+                query="",
+                limit=limit,
+                order_by="ts DESC",
+            )
+        except Exception:
+            return []
+        memories = []
+        for row in rows:
+            memories.append(Memory(
+                id=str(row.get("id", "")),
+                content=row.get("content", ""),
+                role=row.get("role", "user"),
+            ))
+        return memories
+
+    def count(self) -> int:
+        try:
+            result = self._db.count("messages")
+            return result if isinstance(result, int) else 0
+        except Exception:
+            return 0
+
+    def clear(self) -> None:
+        try:
+            self._db.raw_query("DELETE FROM messages")
+        except Exception:
+            pass

coremem/core.py

@@ -0,0 +1,103 @@
+"""MemoryCore — the main entry point for coremem.
+
+Wraps any StoreBackend with heuristics, wake-up context, and ingestion.
+"""
+
+from coremem.backends.base import StoreBackend
+from coremem.heuristics import SearchHeuristics
+from coremem.ingest import ingest_batch, ingest_message
+from coremem.layers import WakeUpContext
+from coremem.types import SearchQuery, SearchResult
+
+
+class MemoryCore:
+    """Zero-LLM memory core for AI agents.
+
+    Dual-backend architecture:
+      - ChromaBackend: Pure ChromaDB (baseline)
+      - HybridBackend: HybridDB SQLite+FTS5+ChromaDB (enhanced)
+
+    Same API regardless of backend.
+
+    Usage:
+        core = MemoryCore(backend=ChromaBackend(path="./memory"))
+        core.ingest("user", "I built a Spitfire model kit")
+        results = core.search("How many model kits?")
+        context = core.wake_up(user_id="alice")
+    """
+
+    def __init__(self, backend: StoreBackend):
+        self._backend = backend
+        self._wakeup = WakeUpContext(backend)
+        self._heuristics = SearchHeuristics()
+
+    @property
+    def backend(self) -> StoreBackend:
+        return self._backend
+
+    def ingest(self, role: str, content: str, session_id: str | None = None) -> str:
+        """Store a message verbatim.
+
+        No LLM extraction. No summarization. Just store the raw text.
+        """
+        return ingest_message(backend=self._backend, role=role, content=content, session_id=session_id)
+
+    def ingest_many(self, messages: list[dict], session_id: str | None = None) -> list[str]:
+        """Store a batch of messages verbatim."""
+        return ingest_batch(backend=self._backend, messages=messages, session_id=session_id)
+
+    def search(self, query: str, limit: int = 10) -> list[SearchResult]:
+        """Search memories and apply deterministic heuristics.
+
+        Pipeline:
+          1. Backend raw search (embedding ± keyword)
+          2. Apply heuristics (keyword overlap, temporal, person name, quoted)
+          3. Session-level dedup (if backend supports it)
+          4. Return ranked results
+
+        All steps are deterministic — zero LLM calls.
+        """
+        sq = SearchQuery(text=query, limit=limit * 3)
+        results = self._backend.search(sq)
+
+        for r in results:
+            r.score = SearchHeuristics.apply_all(
+                query=query,
+                content=r.memory.content,
+                score=r.score,
+                ts=r.memory.ts.isoformat() if r.memory.ts else None,
+            )
+
+        results.sort(key=lambda r: r.score, reverse=True)
+        return results[:limit]
+
+    def wake_up(self, user_id: str = "default", session_id: str | None = None) -> str:
+        """Build the L0+L1 (+ optional L2) wake-up context.
+
+        Returns ~170 tokens of always-on context that the agent can
+        inject into its system prompt without waiting for a tool call.
+        """
+        context = self._wakeup.essential(user_id=user_id)
+
+        if session_id:
+            l2 = self._wakeup.session(session_id=session_id)
+            if l2:
+                context += "\n\n" + l2
+
+        return context
+
+    def deep_search_context(self, query: str, limit: int = 10) -> str | None:
+        """Perform an L3 deep search and return formatted context.
+
+        This is the equivalent of calling the memory_search tool.
+        Returns None if no results found.
+        """
+        return self._wakeup.deep_search(query=query, limit=limit)
+
+    def count(self) -> int:
+        """Return total number of stored memories."""
+        return self._backend.count()
+
+    def clear(self) -> None:
+        """Delete all memories."""
+        self._backend.clear()

coremem/heuristics.py

@@ -0,0 +1,150 @@
+"""Deterministic post-retrieval heuristics — shared by all backends.
+
+All heuristics are zero-LLM, purely pattern-based.
+"""
+
+import re
+
+
+class SearchHeuristics:
+    """Post-retrieval scoring heuristics based on MemPalace's proven patterns.
+
+    Each heuristic applies a deterministic multiplier to results from
+    the backend's raw search. Heuristics are additive — they boost or
+    penalize scores without replacing the embedding ranking.
+    """
+
+    KEYWORD_OVERLAP_WEIGHT = 1.0
+    TEMPORAL_BOOST_FACTOR = 0.15
+    PERSON_NAME_BOOST = 0.40
+    QUOTED_PHRASE_BOOST = 0.60
+    COUNTING_QUESTION_SNIPPET_LENGTH = 3000
+    RECENCY_DECAY_WEIGHT = 0.1
+    RECENCY_DECAY_HALF_LIFE_DAYS = 30
+    STOP_WORDS = {
+        "the", "a", "an", "is", "are", "was", "were", "be", "been",
+        "have", "has", "had", "do", "does", "did", "will", "would",
+        "could", "should", "may", "might", "can", "shall",
+        "to", "of", "in", "for", "on", "with", "at", "by", "from",
+        "and", "or", "but", "not", "so", "if", "as", "than", "that",
+        "this", "these", "those", "it", "its", "i", "me", "my", "we",
+        "our", "you", "your", "he", "she", "they", "them", "their",
+    }
+
+    @classmethod
+    def keyword_overlap(cls, query: str, content: str, score: float) -> float:
+        """Boost score when query keywords appear in content.
+
+        fused = score * (1 + weight * keyword_overlap_ratio)
+        """
+        q_words = {w.lower() for w in re.findall(r"\w+", query) if len(w) > 2}
+        q_words -= cls.STOP_WORDS
+        if not q_words:
+            return score
+
+        c_words = set(re.findall(r"\w+", content.lower()))
+        overlap = len(q_words & c_words) / len(q_words)
+        return score * (1 + cls.KEYWORD_OVERLAP_WEIGHT * overlap)
+
+    @classmethod
+    def temporal_boost(cls, query: str, content_ts: str | None, score: float) -> float:
+        """Boost recent memories when query contains temporal cues.
+
+        Detects patterns like 'current', 'latest', 'now', 'this year',
+        'recently', 'these days' and boosts newer content.
+        """
+        temporal_cues = {
+            "current", "latest", "now", "recently", "recent",
+            "lately", "new", "newest", "these days", "this year",
+            "nowadays", "updated", "today",
+        }
+        q_lower = query.lower()
+        if not any(cue in q_lower for cue in temporal_cues):
+            return score
+
+        if not content_ts:
+            return score
+
+        try:
+            from datetime import datetime
+            ts = datetime.fromisoformat(content_ts)
+            age_days = (datetime.now() - ts).days
+            if age_days < 30:
+                return score * (1 + cls.TEMPORAL_BOOST_FACTOR)
+        except (ValueError, TypeError):
+            pass
+        return score
+
+    @classmethod
+    def recency_decay(cls, content_ts: str | None, score: float) -> float:
+        """Unconditional mild recency boost — applied to every result.
+
+        Uses exponential decay: score * (1 + weight * e^(-age_days / half_life))
+        Very recent content gets ~10% boost, 30-day-old ~3.7%, 60-day ~1.4%.
+        Always applied regardless of query content.
+        """
+        if not content_ts:
+            return score
+
+        try:
+            from datetime import datetime
+            ts = datetime.fromisoformat(content_ts)
+            age_days = max(0, (datetime.now() - ts).days)
+            import math
+            factor = cls.RECENCY_DECAY_WEIGHT * math.exp(-age_days / cls.RECENCY_DECAY_HALF_LIFE_DAYS)
+            return score * (1 + factor)
+        except (ValueError, TypeError):
+            pass
+        return score
+
+    @classmethod
+    def person_name_boost(cls, content: str, score: float) -> float:
+        """Boost content containing proper names (capitalized multi-word)."""
+        names = re.findall(r"\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,2})\b", content)
+        if names:
+            return score * (1 + cls.PERSON_NAME_BOOST)
+        return score
+
+    @classmethod
+    def quoted_phrase_boost(cls, query: str, content: str, score: float) -> float:
+        """Boost when a quoted phrase from the query appears verbatim in content."""
+        quoted = re.findall(r'"([^"]+)"', query)
+        if not quoted:
+            return score
+        for phrase in quoted:
+            if phrase.lower() in content.lower():
+                return score * (1 + cls.QUOTED_PHRASE_BOOST)
+        return score
+
+    @classmethod
+    def is_counting_question(cls, query: str) -> bool:
+        """Detect 'how many' / 'how much total' questions."""
+        q = query.lower()
+        return q.startswith("how many") or "how much total" in q
+
+    @classmethod
+    def extract_date_cues(cls, query: str) -> str | None:
+        """Extract a date reference from the query for temporal scoping."""
+        year_match = re.search(r"\b(20\d{2})\b", query)
+        if year_match:
+            return year_match.group(1)
+
+        month_match = re.search(
+            r"\b(january|february|march|april|may|june|july|"
+            r"august|september|october|november|december)\b",
+            query, re.IGNORECASE,
+        )
+        if month_match:
+            return month_match.group(1)
+
+        return None
+
+    @classmethod
+    def apply_all(cls, query: str, content: str, score: float, ts: str | None = None) -> float:
+        """Apply all applicable heuristics to a single result."""
+        s = cls.keyword_overlap(query, content, score)
+        s = cls.recency_decay(ts, s)
+        s = cls.temporal_boost(query, ts, s)
+        s = cls.person_name_boost(content, s)
+        s = cls.quoted_phrase_boost(query, content, s)
+        return s

coremem/ingest.py

@@ -0,0 +1,73 @@
+"""Verbatim message ingestion — shared pipeline.
+
+All backends ingest raw text without LLM extraction.
+The only processing is deterministic: assign IDs, timestamps,
+and attach metadata (role, session_id).
+
+No fact extraction. No summarization. No LLM calls.
+"""
+
+from datetime import UTC, datetime
+
+from coremem.backends.base import StoreBackend
+from coremem.types import Memory
+
+
+def ingest_message(
+    backend: StoreBackend,
+    role: str,
+    content: str,
+    session_id: str | None = None,
+    ts: datetime | None = None,
+) -> str:
+    """Ingest a single message verbatim.
+
+    Args:
+        backend: The storage backend (ChromaBackend or HybridBackend).
+        role: Message role (user, assistant, tool, system).
+        content: Raw message text — stored as-is, no extraction.
+        session_id: Optional session/thread identifier.
+        ts: Optional timestamp (defaults to now).
+
+    Returns:
+        The storage ID assigned to this memory.
+    """
+    if not content.strip():
+        return ""
+
+    memory = Memory(
+        id="",
+        content=content,
+        role=role,
+        ts=ts or datetime.now(UTC),
+        session_id=session_id,
+    )
+    return backend.ingest(memory)
+
+
+def ingest_batch(
+    backend: StoreBackend,
+    messages: list[dict],
+    session_id: str | None = None,
+) -> list[str]:
+    """Ingest a batch of messages.
+
+    Args:
+        backend: The storage backend.
+        messages: List of {"role": str, "content": str} dicts.
+        session_id: Optional session/thread identifier.
+
+    Returns:
+        List of storage IDs.
+    """
+    ids = []
+    for msg in messages:
+        mid = ingest_message(
+            backend=backend,
+            role=msg.get("role", "user"),
+            content=msg.get("content", ""),
+            session_id=session_id,
+        )
+        if mid:
+            ids.append(mid)
+    return ids

coremem/layers.py

@@ -0,0 +1,88 @@
+"""L0-L3 wake-up context stack.
+
+Inspired by MemPalace's four-layer memory stack and validated against
+the human memory multi-store model (Mujawar et al., 2021).
+
+L0: Identity    — user profile text (~100 tokens, always loaded)
+L1: Essential   — top-ranked recent memories (~500 chars, always loaded)
+L2: On-Demand   — session-specific context (~200-500 chars, on detect)
+L3: Deep Search — full hybrid/semantic search (per explicit query)
+"""
+
+from coremem.backends.base import StoreBackend
+from coremem.heuristics import SearchHeuristics
+
+
+class WakeUpContext:
+    """Build the L0-L3 context stack from a memory backend.
+
+    Usage:
+        ctx = WakeUpContext(backend)
+        l0_l1 = ctx.essential(user_id="alice")     # ~170 tokens, always
+        l2 = ctx.session(session_id="sess_5")       # on session detect
+        l3 = ctx.deep_search("model kits", limit=5) # explicit tool call
+    """
+
+    def __init__(self, backend: StoreBackend):
+        self._backend = backend
+
+    def essential(self, user_id: str = "default") -> str:
+        """Build L0 + L1 context (~170 tokens)."""
+        parts = []
+
+        parts.append(f"[L0: Identity] User: {user_id}")
+
+        recent = self._backend.get_recent(limit=10)
+        if recent:
+            snippets = []
+            for m in recent[:3]:
+                content = m.content[:200]
+                if len(m.content) > 200:
+                    content += "..."
+                snippets.append(f"  - [{m.role}] {content}")
+            parts.append("[L1: Essential] Recent context:\n" + "\n".join(snippets))
+
+        return "\n".join(parts)
+
+    def session(self, session_id: str) -> str | None:
+        """Build L2 context for a specific session."""
+        recent = self._backend.get_recent(limit=20)
+        session_memories = [
+            m for m in recent
+            if m.session_id == session_id
+        ]
+        if not session_memories:
+            return None
+
+        lines = [f"[L2: On-Demand] Session {session_id}:"]
+        for m in session_memories[:5]:
+            content = m.content[:200]
+            if len(m.content) > 200:
+                content += "..."
+            lines.append(f"  - [{m.role}] {content}")
+        return "\n".join(lines)
+
+    def deep_search(self, query: str, limit: int = 10) -> str | None:
+        """Build L3 context from a full search query."""
+        from coremem.types import SearchQuery
+
+        results = self._backend.search(SearchQuery(text=query, limit=limit))
+        if not results:
+            return None
+
+        is_counting = SearchHeuristics.is_counting_question(query)
+
+        lines = [f"[L3: Deep Search] Results for '{query}':"]
+        for r in results:
+            content = r.memory.content
+            if is_counting and len(content) > SearchHeuristics.COUNTING_QUESTION_SNIPPET_LENGTH:
+                content = content[:SearchHeuristics.COUNTING_QUESTION_SNIPPET_LENGTH] + "..."
+            elif len(content) > 500:
+                content = content[:500] + "..."
+
+            lines.append(
+                f"  {r.memory.id[:12]} [{r.memory.role}] "
+                f"(score={r.score:.2f}): {content}"
+            )
+
+        return "\n".join(lines)

coremem/types.py

@@ -0,0 +1,51 @@
+"""Core types for coremem."""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class Memory:
+    """A single memory entry — one message or conversation turn."""
+    id: str
+    content: str
+    role: str = "user"
+    ts: datetime | None = None
+    session_id: str | None = None
+    workspace_id: str | None = None
+    score: float = 0.0
+
+    def dict(self) -> dict:
+        return {
+            "id": self.id,
+            "content": self.content,
+            "role": self.role,
+            "ts": self.ts.isoformat() if self.ts else None,
+            "session_id": self.session_id,
+            "score": self.score,
+        }
+
+
+@dataclass
+class SearchResult:
+    """Result from a memory search."""
+    memory: Memory
+    score: float = 0.0
+    source: str = "semantic"
+
+
+@dataclass
+class SearchQuery:
+    """A search query with optional filters."""
+    text: str
+    limit: int = 10
+    wing: str | None = None
+    room: str | None = None
+
+    def dict(self) -> dict:
+        return {
+            "text": self.text,
+            "limit": self.limit,
+            "wing": self.wing,
+            "room": self.room,
+        }

coremem-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: coremem
+Version: 0.1.0
+Summary: Zero-LLM memory retrieval for AI agents — semantic search and deterministic heuristics
+Author: Eddy Vinck
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,llm,memory,retrieval,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sentence-transformers>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: hybrid
+Requires-Dist: hybriddb>=0.2.0; extra == 'hybrid'
+Description-Content-Type: text/markdown
+
+# CoreMem
+
+> **Zero-LLM memory retrieval for AI agents.** CoreMem gives agents instant access to conversation history — semantic search plus deterministic retrieval heuristics, all without a single API call. Scores **98.0% R@5 on LongMemEval (500 questions)** in the Executive Assistant retrieval stack — no LLM, no tuning, no cloud.
+
+> **Embedded. Local. Open source.** No external APIs, no vector DB services, no internet connection required. Runs entirely on-device with ChromaDB or HybridDB + sentence-transformers. Ships as a single Python package with zero infrastructure dependencies.
+
+**Dual-backend architecture.** Drop-in backends (ChromaDB baseline, HybridDB enhanced) with the same API. Ranking pipeline: backend retrieval → deterministic heuristics → recency-aware rescoring → session-aware retrieval.
+
+```python
+from coremem import MemoryCore
+from coremem.backends.chroma import ChromaBackend
+
+core = MemoryCore(backend=ChromaBackend(path="./memory"))
+
+# Ingest conversation turns
+core.ingest("user", "I visited the Museum of Modern Art today")
+core.ingest("assistant", "That sounds wonderful! How was it?")
+core.ingest("user", "I went to an Ancient Civilizations exhibition at the Natural History Museum")
+
+# Search with deterministic heuristic reranking
+results = core.search("When did I visit art museums?")
+
+for r in results:
+    print(f"[{r.memory.ts}] [{r.memory.role}] {r.memory.content}")
+```
+
+## Why CoreMem?
+
+Every AI agent needs memory. But cloud-based vector search is expensive, slow, and doesn't work offline. Pure embedding similarity misses keyword matches and temporal context. LLM-based memory systems cost tokens per query.
+
+CoreMem solves all three:
+
+| Component | What it does |
+|-----------|-------------|
+| **Semantic search** | Embedding similarity via ChromaDB or HybridDB |
+| **Deterministic heuristics** | Keyword overlap, temporal recency, person-name boost, quoted-phrase matching |
+| **Session deduplication** | One result per conversation, with full context retrieval |
+
+## LongMemEval Results (500 questions, no LLM, no tuning)
+
+| Metric | Score |
+|--------|-------|
+| R@5 | **98.0%** |
+| R@10 | **98.4%** |
+| MRR | 0.944 |
+| P@5 | 0.592 |
+| F1@5 | 0.684 |
+| Selectivity | 11.5% haystack scanned |
+| Rank distribution | #1: 91.8%, #2-3: 5.0%, #4-5: 1.2%, #6-10: 0.4%, >10: 1.6% |
+
+Outperforms MemPalace raw (96.6%) and matches their hybrid v4 held-out (98.4%) — with zero tuning, zero dev-set peeking.
+
+## Installation
+
+```bash
+pip install coremem
+```
+
+With HybridDB backend for enhanced FTS5 + vector hybrid search:
+
+```bash
+pip install coremem[hybrid]
+```
+
+## Core Concepts
+
+### Backends
+
+```python
+# ChromaDB baseline — pure vector search
+from coremem.backends.chroma import ChromaBackend
+core = MemoryCore(backend=ChromaBackend(path="./data"))
+
+# HybridDB enhanced — FTS5 + vector hybrid search
+from coremem.backends.hybrid import HybridBackend
+core = MemoryCore(backend=HybridBackend(path="./data"))
+```
+
+### Ingestion
+
+```python
+# Simple ingestion
+core.ingest("user", "I built a Spitfire model kit", session_id="conv_001")
+
+# Batch ingestion
+from coremem import ingest_batch
+ingest_batch(core, [
+    ("user", "What's the weather today?"),
+    ("assistant", "Sunny with a high of 72°F"),
+], session_id="conv_001")
+```
+
+### Search
+
+```python
+# Basic search
+results = core.search("How many model kits?", limit=10)
+
+# Limit results
+results = core.search("model building projects", limit=5)
+```
+
+### Heuristics
+
+Deterministic, zero-LLM scoring boosts applied to every result:
+
+| Heuristic | What it catches |
+|-----------|----------------|
+| `keyword_overlap` | Exact word matches between query and content |
+| `temporal_boost` | Queries with "latest", "current", "recently" |
+| `recency_decay` | Unconditional exponential decay (30-day half-life) |
+| `person_name_boost` | Proper name mentions in content |
+| `quoted_phrase_boost` | Exact phrase matches in quotes |
+
+```python
+from coremem import SearchHeuristics
+
+# Apply all heuristics to a single result
+score = SearchHeuristics.apply_all(
+    query="latest project",
+    content="Just finished the Q3 project report",
+    score=0.75,
+    ts="2026-05-28T10:00:00Z",
+)
+```
+
+### Wake-Up Context
+
+Give the agent instant situational awareness:
+
+```python
+context = core.wake_up(user_id="alice")
+# Returns a compact string with L0 identity and L1 recent context.
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Author
+
+Eddy Vinck
+
+CoreMem is the retrieval engine behind the [Executive Assistant](https://github.com/open-assistants-lab) agent system. Pairs with [HybridDB](https://github.com/open-assistants-lab) for storage and ConnectKit for real-time sync.

coremem-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+coremem/__init__.py,sha256=_Kg-RdBeYZY-YdCjwN4FtBR2ffAqFNmiNK82i6hRVyM,752
+coremem/core.py,sha256=NngEo5rYO39BniE5eACxN4UnDYttOkns5n608oG6TNQ,3642
+coremem/heuristics.py,sha256=H_vWIDT9-0e02lmLA_Wo32-UPCye6-5hA8z1MTwi-wg,5646
+coremem/ingest.py,sha256=OwfWybRlcMLTwj-Eg-tb7FA9wx8I_fhW8F7DQVOlVUs,1865
+coremem/layers.py,sha256=uwRyHouDti1FrdnjC99OzrhBZCiIzW8kGmQznockSUI,3180
+coremem/types.py,sha256=K3EZHRIMwyBCiIBsrqOvPCTTGYa-DlST29XNsTY0_bc,1150
+coremem/backends/__init__.py,sha256=xrnV5akT7X_sN9p2fmPHQa2kyLc55kk_ufwerVV3xak,119
+coremem/backends/base.py,sha256=VzZUZo2eYSRIHybFSHBfmxJt-dAkpyjowjAtN3rDxuA,1144
+coremem/backends/chroma.py,sha256=PswyxsyonuEVjqUj5WEbVXfyfiq6CEC8yNQ-SBT9G4k,4442
+coremem/backends/hybrid.py,sha256=gSicnJJ6JiLLoBhU1WaGVUfiyEgse02-IJLKXizXU88,5732
+coremem-0.1.0.dist-info/METADATA,sha256=x960_5Xe_T3QF7dkaR9JtYGi_jdNbnjFnbd4rkSAgJo,5628
+coremem-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+coremem-0.1.0.dist-info/licenses/LICENSE,sha256=0VqBFOKolO6nkZLiHzpMlKlFlodudmA0C8xu-sf-Z7M,1067
+coremem-0.1.0.dist-info/RECORD,,

coremem-0.1.0.dist-info/WHEEL

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

coremem-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddy Vinck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.