rekal 0.0.3__tar.gz

rekal-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run ruff check rekal/ tests/
+      - run: uv run ruff format --check rekal/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run ty check rekal/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --frozen
+      - run: uv run pytest --cov=rekal --cov-report=term-missing --cov-fail-under=100 tests/

rekal-0.0.3/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: gh release create "${{ github.ref_name }}" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

rekal-0.0.3/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+sdist/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv — lockfile is tracked for reproducible CI
+# uv.lock
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Type checkers
+.ty_cache/
+.mypy_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# rekal database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Generated version file
+rekal/_version.py
+
+# Claude Code
+.claude/
+
+# Environment
+.env
+.env.*

rekal-0.0.3/AGENTS.md

@@ -0,0 +1,170 @@
+# rekal — Agent Instructions
+
+## What this project is
+
+rekal is a Model Context Protocol (MCP) server that gives LLMs persistent long-term memory.
+It uses hybrid search (FTS5 + vector + recency) in a single SQLite file.
+Python 3.14+, installed via `pip install rekal`, runs as a stdio MCP server.
+
+## Architecture
+
+```
+MCP Client
+  │ stdio (JSON-RPC)
+  │
+  mcp_adapter.py          ← FastMCP server, lifespan (creates/closes DB)
+  │
+  ├── tools/core.py       ─┐
+  ├── tools/introspection.py│─ thin @mcp.tool() wrappers, delegate to SqliteDatabase
+  ├── tools/smart_write.py  │
+  └── tools/conversations.py┘
+                            │
+                    sqlite_adapter.py ← SqliteDatabase @dataclass, ALL SQL lives here
+                            │
+                            ├── SQLite (memories, conversations, tags, conflicts)
+                            ├── FTS5 (full-text index, auto-synced via triggers)
+                            └── sqlite-vec (vector index)
+```
+
+### Key rules
+
+- `SqliteDatabase` is a `@dataclass` holding the `aiosqlite.Connection` and ALL query methods. Every SQL statement lives here. No SQL in tool files.
+- Tool modules in `adapters/tools/` are thin wrappers. They register MCP tools via `@mcp.tool()` and call methods on `SqliteDatabase`.
+- `mcp_adapter.py` creates the FastMCP server, manages lifespan, and imports tool modules so they register.
+- Adding a new tool = add a method to `SqliteDatabase` + add a thin tool wrapper in the appropriate `tools/*.py` file.
+
+## Python style — modern, strict, no shortcuts
+
+### Never use `Any`
+
+Zero tolerance. Every value has a real type. If you reach for `Any`, find the actual type.
+Use `TYPE_CHECKING` imports, union types, `Protocol`, or type aliases instead.
+
+```python
+# Correct
+SqlParam = str | int | float | bytes | None
+params: list[SqlParam] = []
+
+# Wrong
+params: list[Any] = []
+```
+
+### No underscore prefixes on attributes or methods
+
+Public by default. No `self._db`, no `_helper()`, no `_CONSTANT`.
+Use plain names: `self.db`, `helper()`, `SCHEMA`.
+
+```python
+# Correct
+@dataclass
+class SqliteDatabase:
+    db: aiosqlite.Connection
+    embed: EmbeddingFunc
+
+# Wrong
+class SqliteDatabase:
+    def __init__(self, db, embed):
+        self._db = db
+        self._embed = embed
+```
+
+### No mutable globals
+
+No module-level mutable state. Constants like `SCHEMA` (a frozen SQL string) and type aliases like `SqlParam` are fine.
+For values that might look like globals, use functions or dataclass fields instead.
+
+```python
+# Correct
+def default_db_path() -> str:
+    return str(Path.home() / ".rekal" / "memory.db")
+
+# Wrong
+_DEFAULT_DB_PATH = str(Path.home() / ".rekal" / "memory.db")
+```
+
+### Use dataclasses everywhere possible
+
+Prefer `@dataclass` over hand-written `__init__`. Pydantic `BaseModel` only where serialization is needed (models.py).
+
+### Use `Annotated` with `Field(description=...)` on all MCP tool parameters
+
+Every tool parameter (except `ctx`) must have a description for the MCP schema.
+
+```python
+@mcp.tool()
+async def memory_store(
+    ctx: Context,
+    content: Annotated[str, Field(description="The text content to store")],
+    limit: Annotated[int, Field(description="Maximum number of results")] = 10,
+) -> str:
+```
+
+### Type annotations on everything
+
+Every function parameter, return type, and non-obvious variable. Use `from __future__ import annotations` in every file.
+
+### Use union syntax, not Optional
+
+```python
+# Correct
+project: str | None = None
+
+# Wrong
+project: Optional[str] = None
+```
+
+## Testing
+
+### 100% coverage, no exceptions
+
+Every line tested. If truly untestable (e.g., defensive except for impossible conditions), add `# pragma: no cover` with explanation.
+
+### No mocking, no monkey patching
+
+Use real implementations:
+- Real in-memory SQLite via `:memory:` (sub-millisecond, tests real SQL)
+- Deterministic hash-based embeddings from `conftest.py` (fast, deterministic, correct shape)
+- Real MCP tool functions called with constructed context objects
+
+### Test structure
+
+```
+tests/
+├── conftest.py                  # db fixture (in-memory), deterministic_embed
+├── test_sqlite_adapter.py       # Direct DB operations
+├── test_search.py               # Hybrid search scoring
+├── test_introspection.py        # memory_similar, topics, timeline, etc.
+├── test_smart_write.py          # supersede, build_context
+├── test_conversations.py        # Conversation DAG operations
+├── test_scoring.py              # Score normalization math
+├── test_embeddings.py           # Embedding utilities
+├── test_core_tools.py           # MCP tool wrappers for core
+├── test_introspection_tools.py  # MCP tool wrappers for introspection
+├── test_smart_write_tools.py    # MCP tool wrappers for smart_write
+├── test_conversation_tools.py   # MCP tool wrappers for conversations
+├── test_mcp_adapter.py          # Lifespan test
+└── test_cli.py                  # CLI commands
+```
+
+## CI checks — all must pass
+
+```bash
+ruff check rekal/ tests/
+ruff format --check rekal/ tests/
+ty check rekal/ tests/
+pytest --cov=rekal --cov-report=term-missing --cov-fail-under=100 tests/
+```
+
+## Tooling config
+
+- **ruff** — lint + format, line-length 99, target py314
+- **ty** — type checker, python-version 3.14
+- **pytest** — asyncio_mode auto, 100% coverage required
+
+## Dependencies
+
+- `mcp[cli]` — FastMCP framework
+- `aiosqlite` — async SQLite
+- `sqlite-vec` — vector search extension
+- `fastembed` — ONNX embeddings (lazy-loaded)
+- `pydantic` — models and validation

rekal-0.0.3/CLAUDE.md

@@ -0,0 +1 @@
+Read AGENTS.md before doing anything.

rekal-0.0.3/LICENSE

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

rekal-0.0.3/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: rekal
+Version: 0.0.3
+Summary: Long-term memory MCP server for LLMs — hybrid search in a single SQLite file
+Author: Jan Bjorge
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,mcp,memory,sqlite,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sqlite-vec>=0.1.6
+Description-Content-Type: text/markdown
+
+# rekal
+
+Long-term memory MCP server for LLMs. Hybrid search (FTS5 + vector + recency) in a single SQLite file.
+
+## Install
+
+```bash
+pip install rekal
+```
+
+## Usage
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "rekal": {
+      "command": "rekal"
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+rekal serve    # Run as MCP server (default)
+rekal health   # Show database health report
+rekal export   # Export all memories as JSON
+```

rekal-0.0.3/README.md

@@ -0,0 +1,31 @@
+# rekal
+
+Long-term memory MCP server for LLMs. Hybrid search (FTS5 + vector + recency) in a single SQLite file.
+
+## Install
+
+```bash
+pip install rekal
+```
+
+## Usage
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "rekal": {
+      "command": "rekal"
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+rekal serve    # Run as MCP server (default)
+rekal health   # Show database health report
+rekal export   # Export all memories as JSON
+```

rekal-0.0.3/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rekal"
+dynamic = ["version"]
+description = "Long-term memory MCP server for LLMs — hybrid search in a single SQLite file"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+authors = [{ name = "Jan Bjorge" }]
+keywords = ["mcp", "memory", "llm", "sqlite", "vector-search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "aiosqlite>=0.20.0",
+    "sqlite-vec>=0.1.6",
+    "fastembed>=0.4.0",
+    "pydantic>=2.0.0",
+]
+
+[project.scripts]
+rekal = "rekal.__main__:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "rekal/_version.py"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 99
+extend-exclude = ["rekal/_version.py"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "A",
+    "SIM",
+    "TCH",
+    "RUF",
+    "PTH",
+    "RET",
+    "ARG",
+    "ERA",
+    "TID",
+    "PL",
+]
+ignore = [
+    "PLR0913",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLR2004", "TCH001", "TCH002", "TCH003", "PLC0415", "ARG001"]
+"rekal/adapters/tools/**" = ["TCH001", "TCH002"]
+"rekal/__main__.py" = ["PLC0415"]
+"rekal/embeddings.py" = ["PLC0415"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["rekal"]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["rekal"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+omit = ["rekal/_version.py"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.10",
+    "ty>=0.0.29",
+]

rekal-0.0.3/rekal/__init__.py

@@ -0,0 +1,5 @@
+"""rekal — long-term memory MCP server for LLMs."""
+
+from rekal._version import __version__
+
+__all__ = ["__version__"]

rekal-0.0.3/rekal/__main__.py

@@ -0,0 +1,77 @@
+"""CLI entry point: rekal, rekal health, rekal export."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+
+from rekal.adapters.mcp_adapter import default_db_path
+from rekal.adapters.sqlite_adapter import SqliteDatabase
+from rekal.embeddings import FastEmbedder
+
+
+def get_db_path(args: argparse.Namespace) -> str:
+    return args.db or os.environ.get("REKAL_DB_PATH", default_db_path())
+
+
+async def run_serve() -> None:  # pragma: no cover — interactive stdio server
+    from rekal.adapters.mcp_adapter import mcp
+
+    await mcp.run_stdio_async()
+
+
+async def run_health(db_path: str) -> None:
+    if not Path(db_path).exists():
+        print(f"Database not found: {db_path}")
+        sys.exit(1)
+
+    embed = FastEmbedder()
+    db = await SqliteDatabase.create(db_path, embed)
+    try:
+        report = await db.memory_health()
+        print(json.dumps(report.model_dump(), indent=2))
+    finally:
+        await db.close()
+
+
+async def run_export(db_path: str) -> None:
+    if not Path(db_path).exists():
+        print(f"Database not found: {db_path}")
+        sys.exit(1)
+
+    embed = FastEmbedder()
+    db = await SqliteDatabase.create(db_path, embed)
+    try:
+        memories = await db.memory_timeline(limit=100_000)
+        data = [m.model_dump() for m in memories]
+        print(json.dumps(data, indent=2))
+    finally:
+        await db.close()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="rekal", description="rekal memory MCP server")
+    parser.add_argument("--db", help="Path to SQLite database file")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("serve", help="Run as MCP server (default)")
+    sub.add_parser("health", help="Show database health report")
+    sub.add_parser("export", help="Export all memories as JSON")
+
+    args = parser.parse_args()
+    command = args.command or "serve"
+
+    if command == "serve":  # pragma: no cover — interactive stdio server
+        asyncio.run(run_serve())
+    elif command == "health":
+        asyncio.run(run_health(get_db_path(args)))
+    elif command == "export":
+        asyncio.run(run_export(get_db_path(args)))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

rekal-0.0.3/rekal/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.3'
+__version_tuple__ = version_tuple = (0, 0, 3)
+
+__commit_id__ = commit_id = None

rekal-0.0.3/rekal/adapters/mcp_adapter.py

@@ -0,0 +1,43 @@
+"""FastMCP server, lifespan, and DB initialization."""
+
+from __future__ import annotations
+
+import os
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from mcp.server.fastmcp import FastMCP
+
+from rekal.adapters.sqlite_adapter import SqliteDatabase
+from rekal.embeddings import FastEmbedder
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+def default_db_path() -> str:
+    return str(Path.home() / ".rekal" / "memory.db")
+
+
+@dataclass
+class AppContext:
+    db: SqliteDatabase
+
+
+@asynccontextmanager
+async def lifespan(_server: FastMCP) -> AsyncIterator[AppContext]:
+    db_path = os.environ.get("REKAL_DB_PATH", default_db_path())
+    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+    embed = FastEmbedder()
+    db = await SqliteDatabase.create(db_path, embed, dimensions=embed.dimensions)
+    try:
+        yield AppContext(db=db)
+    finally:
+        await db.close()
+
+
+mcp = FastMCP("rekal", lifespan=lifespan)
+
+import rekal.adapters.tools  # noqa: E402, F401