remembrane 0.1.0__tar.gz

remembrane-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: ruff check src tests
+      - run: pytest --cov=remembrane --cov-report=term-missing

remembrane-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+.pytest_cache/
+.ruff_cache/
+*.db
+.venv/
+pytest-cache-files-*/

remembrane-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to remembrane
+
+Thanks for your interest!
+
+## Setup
+
+```bash
+git clone https://github.com/satyasairay/remembrane
+cd remembrane
+pip install -e .[dev]
+pytest
+```
+
+## Guidelines
+
+- Keep the core dependency-free. New integrations go in `src/remembrane/adapters/` as duck-typed, optional modules.
+- Every PR needs tests. Run `pytest` and `ruff check src tests` before submitting.
+- One feature per PR. Open an issue first for anything large.
+
+## Ideas welcome
+
+Good first contributions: new framework adapters, embedder backends, recall strategies (MMR, hybrid keyword+vector), benchmarks.

remembrane-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satyasai Ray
+
+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.

remembrane-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: remembrane
+Version: 0.1.0
+Summary: Local-first persistent memory for AI agents. SQLite-backed, zero required dependencies, pluggable embeddings, framework adapters and an MCP server.
+Project-URL: Homepage, https://github.com/satyasairay/remembrane
+Project-URL: Issues, https://github.com/satyasairay/remembrane/issues
+Author-email: Satyasai Ray <satyasairay@yahoo.com>, Satyasai Ray <satyasairay2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,crewai,langchain,llm,local-first,mcp,memory,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: sentence-transformers
+Requires-Dist: sentence-transformers>=2.2; extra == 'sentence-transformers'
+Description-Content-Type: text/markdown
+
+# remembrane
+
+**Local-first persistent memory for AI agents.** SQLite-backed, zero required dependencies, pluggable embeddings, with adapters for LangChain and CrewAI and a built-in MCP server.
+
+```bash
+pip install remembrane
+```
+
+## Why
+
+Agents forget everything between sessions. Existing memory solutions are cloud APIs, require a vector database, or drag in a heavyweight framework. `remembrane` is the opposite:
+
+- **One file.** Your agent's entire memory is a SQLite database you can copy, back up, diff, or delete.
+- **Zero required dependencies.** The default embedder is pure stdlib. `pip install remembrane` pulls in nothing else.
+- **Human-like recall.** Results are ranked by a composite of semantic similarity, recency decay (memories halve in weight every week by default), and importance. Recalled memories are *reinforced* — spaced repetition for agents.
+- **Framework-agnostic.** Use it bare, through the LangChain or CrewAI adapters, or expose it to any MCP-capable agent (like Claude) as an MCP server.
+
+## Quick start
+
+```python
+from remembrane import MemoryStore
+
+mem = MemoryStore("agent.db")            # or ":memory:" for ephemeral
+
+mem.store("User prefers dark mode", importance=0.8)
+mem.store("Deploy target is AWS us-east-1", namespace="ops")
+
+results = mem.recall("what theme does the user like?")
+print(results[0].memory.content)         # → "User prefers dark mode"
+print(results[0].score)                  # similarity × recency × importance
+```
+
+### Memory lifecycle
+
+```python
+mem.reinforce(memory_id)                  # strengthen: slower decay, higher rank
+mem.forget(memory_id)                     # delete one
+mem.forget(namespace="ops")               # delete a namespace
+mem.forget(older_than_seconds=30*86400)   # prune stale memories
+mem.consolidate()                         # merge near-duplicates
+mem.export()                              # plain dicts, ready for json.dump
+```
+
+### Tuning recall
+
+```python
+from remembrane import MemoryStore, ScoringConfig
+
+mem = MemoryStore(
+    "agent.db",
+    scoring=ScoringConfig(
+        weight_similarity=0.7,
+        weight_recency=0.15,
+        weight_importance=0.15,
+        half_life_seconds=7 * 24 * 3600,   # recency halves every week
+    ),
+)
+```
+
+## Embedders
+
+The default `HashEmbedder` is deterministic, offline, and dependency-free — it hashes word and character n-grams. That makes similarity *lexical*, not semantic. It works well for typical agent memories (facts, preferences, short statements). For true semantic recall, plug in a real model:
+
+```python
+from remembrane import MemoryStore, SentenceTransformerEmbedder, OpenAIEmbedder
+
+mem = MemoryStore("agent.db", embedder=SentenceTransformerEmbedder())   # local, pip install remembrane[sentence-transformers]
+mem = MemoryStore("agent.db", embedder=OpenAIEmbedder())                # API,   pip install remembrane[openai]
+```
+
+Any object with `embed(texts) -> List[List[float]]` and a `dimension` attribute works.
+
+Note: don't mix embedders in one database. Vectors from different embedders aren't comparable.
+
+## LangChain
+
+```python
+from remembrane import MemoryStore
+from remembrane.adapters import RemembraneChatMemory
+
+memory = RemembraneChatMemory(MemoryStore("agent.db"), session_id="user-42")
+
+memory.save_context({"input": "my favorite color is teal"}, {"output": "Noted!"})
+memory.load_memory_variables({"input": "what color do I like?"})
+# {'history': 'human: my favorite color is teal\nai: Noted!'}
+```
+
+Unlike buffer memory, this retrieves the exchanges *relevant to the current input* — the context window stays small no matter how long the history grows.
+
+## CrewAI
+
+```python
+from remembrane import MemoryStore
+from remembrane.adapters import RemembraneStorage
+
+storage = RemembraneStorage(MemoryStore("crew.db"))
+storage.save("the deadline is next friday", metadata={"task": "planning"})
+storage.search("when is the deadline?")
+```
+
+## MCP server
+
+Give any MCP-capable agent (e.g. Claude Desktop, Claude Code) persistent memory:
+
+```bash
+pip install remembrane[mcp]
+remembrane-mcp --db ~/agent-memory.db
+```
+
+```json
+{
+  "mcpServers": {
+    "remembrane": {
+      "command": "remembrane-mcp",
+      "args": ["--db", "/path/to/agent-memory.db"]
+    }
+  }
+}
+```
+
+Tools exposed: `memory_store`, `memory_recall`, `memory_forget`, `memory_reinforce`, `memory_stats`.
+
+## CLI
+
+```bash
+remembrane --db agent.db store "the user prefers dark mode" --importance 0.8
+remembrane --db agent.db recall "what theme?"
+remembrane --db agent.db list
+remembrane --db agent.db stats
+remembrane --db agent.db export > backup.json
+```
+
+## How ranking works
+
+```
+score = 0.7·similarity + 0.15·recency + 0.15·importance
+recency = exp(−ln2 · age / half_life)
+```
+
+`age` is measured from the memory's **last access**, not creation — every recall resets the decay clock. Frequently-used memories stay vivid; untouched ones fade. All weights and the half-life are configurable.
+
+## Design choices
+
+- **SQLite over a vector DB** — agent memory stores are small (thousands, not billions, of rows). Brute-force cosine over a few thousand vectors is sub-millisecond, and you gain transactions, a single portable file, and zero infra.
+- **No background daemon** — decay is computed at read time, so nothing runs when your agent doesn't.
+- **Duck-typed adapters** — `remembrane` never imports langchain or crewai; the adapters match their interfaces structurally, so there are no version-pinning fights.
+
+## Development
+
+```bash
+git clone https://github.com/satyasairay/remembrane
+cd remembrane
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

remembrane-0.1.0/README.md

@@ -0,0 +1,159 @@
+# remembrane
+
+**Local-first persistent memory for AI agents.** SQLite-backed, zero required dependencies, pluggable embeddings, with adapters for LangChain and CrewAI and a built-in MCP server.
+
+```bash
+pip install remembrane
+```
+
+## Why
+
+Agents forget everything between sessions. Existing memory solutions are cloud APIs, require a vector database, or drag in a heavyweight framework. `remembrane` is the opposite:
+
+- **One file.** Your agent's entire memory is a SQLite database you can copy, back up, diff, or delete.
+- **Zero required dependencies.** The default embedder is pure stdlib. `pip install remembrane` pulls in nothing else.
+- **Human-like recall.** Results are ranked by a composite of semantic similarity, recency decay (memories halve in weight every week by default), and importance. Recalled memories are *reinforced* — spaced repetition for agents.
+- **Framework-agnostic.** Use it bare, through the LangChain or CrewAI adapters, or expose it to any MCP-capable agent (like Claude) as an MCP server.
+
+## Quick start
+
+```python
+from remembrane import MemoryStore
+
+mem = MemoryStore("agent.db")            # or ":memory:" for ephemeral
+
+mem.store("User prefers dark mode", importance=0.8)
+mem.store("Deploy target is AWS us-east-1", namespace="ops")
+
+results = mem.recall("what theme does the user like?")
+print(results[0].memory.content)         # → "User prefers dark mode"
+print(results[0].score)                  # similarity × recency × importance
+```
+
+### Memory lifecycle
+
+```python
+mem.reinforce(memory_id)                  # strengthen: slower decay, higher rank
+mem.forget(memory_id)                     # delete one
+mem.forget(namespace="ops")               # delete a namespace
+mem.forget(older_than_seconds=30*86400)   # prune stale memories
+mem.consolidate()                         # merge near-duplicates
+mem.export()                              # plain dicts, ready for json.dump
+```
+
+### Tuning recall
+
+```python
+from remembrane import MemoryStore, ScoringConfig
+
+mem = MemoryStore(
+    "agent.db",
+    scoring=ScoringConfig(
+        weight_similarity=0.7,
+        weight_recency=0.15,
+        weight_importance=0.15,
+        half_life_seconds=7 * 24 * 3600,   # recency halves every week
+    ),
+)
+```
+
+## Embedders
+
+The default `HashEmbedder` is deterministic, offline, and dependency-free — it hashes word and character n-grams. That makes similarity *lexical*, not semantic. It works well for typical agent memories (facts, preferences, short statements). For true semantic recall, plug in a real model:
+
+```python
+from remembrane import MemoryStore, SentenceTransformerEmbedder, OpenAIEmbedder
+
+mem = MemoryStore("agent.db", embedder=SentenceTransformerEmbedder())   # local, pip install remembrane[sentence-transformers]
+mem = MemoryStore("agent.db", embedder=OpenAIEmbedder())                # API,   pip install remembrane[openai]
+```
+
+Any object with `embed(texts) -> List[List[float]]` and a `dimension` attribute works.
+
+Note: don't mix embedders in one database. Vectors from different embedders aren't comparable.
+
+## LangChain
+
+```python
+from remembrane import MemoryStore
+from remembrane.adapters import RemembraneChatMemory
+
+memory = RemembraneChatMemory(MemoryStore("agent.db"), session_id="user-42")
+
+memory.save_context({"input": "my favorite color is teal"}, {"output": "Noted!"})
+memory.load_memory_variables({"input": "what color do I like?"})
+# {'history': 'human: my favorite color is teal\nai: Noted!'}
+```
+
+Unlike buffer memory, this retrieves the exchanges *relevant to the current input* — the context window stays small no matter how long the history grows.
+
+## CrewAI
+
+```python
+from remembrane import MemoryStore
+from remembrane.adapters import RemembraneStorage
+
+storage = RemembraneStorage(MemoryStore("crew.db"))
+storage.save("the deadline is next friday", metadata={"task": "planning"})
+storage.search("when is the deadline?")
+```
+
+## MCP server
+
+Give any MCP-capable agent (e.g. Claude Desktop, Claude Code) persistent memory:
+
+```bash
+pip install remembrane[mcp]
+remembrane-mcp --db ~/agent-memory.db
+```
+
+```json
+{
+  "mcpServers": {
+    "remembrane": {
+      "command": "remembrane-mcp",
+      "args": ["--db", "/path/to/agent-memory.db"]
+    }
+  }
+}
+```
+
+Tools exposed: `memory_store`, `memory_recall`, `memory_forget`, `memory_reinforce`, `memory_stats`.
+
+## CLI
+
+```bash
+remembrane --db agent.db store "the user prefers dark mode" --importance 0.8
+remembrane --db agent.db recall "what theme?"
+remembrane --db agent.db list
+remembrane --db agent.db stats
+remembrane --db agent.db export > backup.json
+```
+
+## How ranking works
+
+```
+score = 0.7·similarity + 0.15·recency + 0.15·importance
+recency = exp(−ln2 · age / half_life)
+```
+
+`age` is measured from the memory's **last access**, not creation — every recall resets the decay clock. Frequently-used memories stay vivid; untouched ones fade. All weights and the half-life are configurable.
+
+## Design choices
+
+- **SQLite over a vector DB** — agent memory stores are small (thousands, not billions, of rows). Brute-force cosine over a few thousand vectors is sub-millisecond, and you gain transactions, a single portable file, and zero infra.
+- **No background daemon** — decay is computed at read time, so nothing runs when your agent doesn't.
+- **Duck-typed adapters** — `remembrane` never imports langchain or crewai; the adapters match their interfaces structurally, so there are no version-pinning fights.
+
+## Development
+
+```bash
+git clone https://github.com/satyasairay/remembrane
+cd remembrane
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

remembrane-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remembrane"
+version = "0.1.0"
+description = "Local-first persistent memory for AI agents. SQLite-backed, zero required dependencies, pluggable embeddings, framework adapters and an MCP server."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "Satyasai Ray", email = "satyasairay@yahoo.com" },
+  { name = "Satyasai Ray", email = "satyasairay2@gmail.com" },
+]
+keywords = ["ai", "agents", "memory", "llm", "mcp", "langchain", "crewai", "sqlite", "local-first"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/satyasairay/remembrane"
+Issues = "https://github.com/satyasairay/remembrane/issues"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+sentence-transformers = ["sentence-transformers>=2.2"]
+mcp = ["mcp>=1.0"]
+dev = ["pytest>=7.0", "pytest-cov", "ruff"]
+
+[project.scripts]
+remembrane = "remembrane.cli:main"
+remembrane-mcp = "remembrane.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/remembrane"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

remembrane-0.1.0/src/remembrane/__init__.py

@@ -0,0 +1,17 @@
+"""remembrane — local-first persistent memory for AI agents."""
+from .embedders import HashEmbedder, OpenAIEmbedder, SentenceTransformerEmbedder, cosine_similarity
+from .models import Memory, RecallResult
+from .scoring import ScoringConfig
+from .store import MemoryStore
+
+__version__ = "0.1.0"
+__all__ = [
+    "MemoryStore",
+    "Memory",
+    "RecallResult",
+    "ScoringConfig",
+    "HashEmbedder",
+    "OpenAIEmbedder",
+    "SentenceTransformerEmbedder",
+    "cosine_similarity",
+]

remembrane-0.1.0/src/remembrane/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Framework adapters for remembrane.
+
+Adapters are duck-typed against their target frameworks so remembrane never
+hard-depends on them. Import errors only occur if you actually use an adapter
+without its framework installed.
+"""
+from .crewai import RemembraneStorage
+from .langchain import RemembraneChatMemory
+
+__all__ = ["RemembraneChatMemory", "RemembraneStorage"]

remembrane-0.1.0/src/remembrane/adapters/crewai.py

@@ -0,0 +1,47 @@
+"""CrewAI-compatible storage adapter.
+
+Duck-typed against crewai's external-memory Storage interface
+(save / search / reset), so it works without importing crewai itself.
+
+Example::
+
+    from remembrane import MemoryStore
+    from remembrane.adapters import RemembraneStorage
+
+    storage = RemembraneStorage(MemoryStore("crew.db"))
+    # pass wherever CrewAI accepts a custom storage backend,
+    # or call .save() / .search() directly.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..store import MemoryStore
+
+
+class RemembraneStorage:
+    """Storage backend backed by a remembrane MemoryStore."""
+
+    def __init__(self, store: MemoryStore, namespace: str = "crew"):
+        self.store = store
+        self.namespace = namespace
+
+    def save(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> None:
+        self.store.store(str(value), namespace=self.namespace, metadata=metadata or {})
+
+    def search(self, query: str, limit: int = 5, score_threshold: float = 0.0) -> List[Dict[str, Any]]:
+        results = self.store.recall(
+            query, k=limit, namespace=self.namespace, min_score=score_threshold
+        )
+        return [
+            {
+                "id": r.memory.id,
+                "context": r.memory.content,
+                "metadata": r.memory.metadata,
+                "score": r.score,
+            }
+            for r in results
+        ]
+
+    def reset(self) -> None:
+        self.store.forget(namespace=self.namespace)

remembrane-0.1.0/src/remembrane/adapters/langchain.py

@@ -0,0 +1,73 @@
+"""LangChain-compatible memory adapter.
+
+Duck-typed against LangChain's memory interface (load_memory_variables /
+save_context / clear), so it works without importing langchain itself.
+
+Example::
+
+    from remembrane import MemoryStore
+    from remembrane.adapters import RemembraneChatMemory
+
+    memory = RemembraneChatMemory(MemoryStore("agent.db"), session_id="user-42")
+    # use anywhere LangChain expects a memory object,
+    # or call .save_context() / .load_memory_variables() directly.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ..store import MemoryStore
+
+
+class RemembraneChatMemory:
+    """Persistent, semantically-recalled conversation memory.
+
+    Instead of replaying the full transcript, ``load_memory_variables`` returns
+    the memories most relevant to the *current input*, ranked by
+    similarity x recency x importance.
+    """
+
+    memory_key: str = "history"
+
+    def __init__(
+        self,
+        store: MemoryStore,
+        session_id: str = "default",
+        k: int = 6,
+        input_key: str = "input",
+        output_key: str = "output",
+    ):
+        self.store = store
+        self.session_id = session_id
+        self.k = k
+        self.input_key = input_key
+        self.output_key = output_key
+
+    @property
+    def memory_variables(self) -> List[str]:
+        return [self.memory_key]
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, Any]) -> None:
+        """Persist one exchange as two memories (human + ai)."""
+        human = str(inputs.get(self.input_key, "")).strip()
+        ai = str(outputs.get(self.output_key, "")).strip()
+        if human:
+            self.store.store(human, namespace=self.session_id, metadata={"role": "human"})
+        if ai:
+            self.store.store(ai, namespace=self.session_id, metadata={"role": "ai"})
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, str]:
+        """Return the k memories most relevant to the current input."""
+        query = str(inputs.get(self.input_key, "")).strip()
+        if not query:
+            memories = self.store.all(self.session_id)[-self.k :]
+            lines = [f"{m.metadata.get('role', '?')}: {m.content}" for m in memories]
+        else:
+            results = self.store.recall(query, k=self.k, namespace=self.session_id)
+            lines = [
+                f"{r.memory.metadata.get('role', '?')}: {r.memory.content}" for r in results
+            ]
+        return {self.memory_key: "\n".join(lines)}
+
+    def clear(self) -> None:
+        self.store.forget(namespace=self.session_id)