rememble 0.1.1__tar.gz

rememble-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.ruff_cache/
+plans/
+CLAUDE.md
+.envrc
+.python-version

rememble-0.1.1/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install uv for fast dependency resolution
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+COPY pyproject.toml .
+COPY src/ src/
+
+RUN uv sync --no-dev --frozen 2>/dev/null || uv sync --no-dev
+
+ENV REMEMBLE_DB_PATH=/data/memory.db
+
+ENTRYPOINT ["uv", "run", "rememble"]

rememble-0.1.1/Makefile

@@ -0,0 +1,40 @@
+.PHONY: dev test lint fmt check bump publish release
+
+BUMP ?= patch
+
+dev: ## Install in development mode
+	uv sync --all-extras
+	@echo "✓ Development mode ready"
+
+test: ## Run tests
+	uv run pytest -v
+
+lint: ## Lint + type check
+	uv run ruff check rememble/ tests/
+	uv run basedpyright rememble/
+
+fmt: ## Format + fix imports
+	uv run ruff format rememble/ tests/
+	uv run ruff check --fix rememble/ tests/
+
+check: fmt lint test ## Format, lint, type check, test
+
+bump: ## Bump version (BUMP=major|minor|patch)
+	uv version --bump $(BUMP)
+
+publish: ## Build + publish to PyPI
+	rm -rf dist/
+	uv build
+	uv publish
+
+release: check ## Full release: fmt, lint, test, bump, tag, push, publish
+	@if [ -n "$$(git status --porcelain)" ]; then echo "ERROR: dirty working tree" && exit 1; fi
+	uv version --bump $(BUMP)
+	$(eval VERSION := $(shell uv version --short))
+	git add pyproject.toml uv.lock
+	git commit -m "chore(release): v$(VERSION)"
+	git tag "v$(VERSION)"
+	git push && git push --tags
+	$(MAKE) publish
+
+.DEFAULT_GOAL := dev

rememble-0.1.1/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: rememble
+Version: 0.1.1
+Summary: Local MCP memory server with hybrid search, knowledge graph, and RAG
+Author-email: Nik Cubrilovic <git@nikcub.me>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: tiktoken>=0.8
+Provides-Extra: all
+Requires-Dist: onnxruntime>=1.19; extra == 'all'
+Requires-Dist: sentence-transformers>=3.0; extra == 'all'
+Provides-Extra: local
+Requires-Dist: onnxruntime>=1.19; extra == 'local'
+Requires-Dist: sentence-transformers>=3.0; extra == 'local'
+Description-Content-Type: text/markdown
+
+# Rememble
+
+Local-first memory server with hybrid search, knowledge graph, and RAG context assembly.
+
+SQLite + sqlite-vec + FTS5 backend. Works with any MCP client.
+
+## Features
+
+- Hybrid search: BM25 + vector KNN + temporal scoring (RRF fusion)
+- Knowledge graph: entities, observations, relations
+- Token-budgeted RAG context assembly
+- Multiple embedding providers: Ollama, local (sentence-transformers), OpenAI-compat
+
+## Install
+
+```bash
+uv sync
+```
+
+## MCP Client Setup
+
+### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "rememble": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/Rememble", "rememble"]
+    }
+  }
+}
+```
+
+## Configuration
+
+Config file: `~/.rememble/config.json` (auto-created on first run).
+
+All fields can be overridden via env vars with `REMEMBLE_` prefix and `__` as nested delimiter.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `REMEMBLE_DB_PATH` | `~/.rememble/memory.db` | SQLite database path |
+| `REMEMBLE_EMBEDDING__PROVIDER` | `ollama` | `ollama` \| `local` \| `compat` |
+| `REMEMBLE_EMBEDDING__MODEL` | `nomic-embed-text` | Model name for active provider |
+| `REMEMBLE_EMBEDDING__DIMENSIONS` | `768` | Embedding dimensions |
+| `REMEMBLE_EMBEDDING__OLLAMA_URL` | `http://localhost:11434` | Ollama base URL |
+| `REMEMBLE_EMBEDDING__API_TYPE` | `openrouter` | Label for compat provider (logging only) |
+| `REMEMBLE_EMBEDDING__API_ENDPOINT` | `https://openrouter.ai/api/v1` | OpenAI-compat base URL |
+| `REMEMBLE_EMBEDDING__API_KEY` | — | API key (or set `OPENROUTER_API_KEY` / `OPENAI_API_KEY`) |
+
+## Embedding Providers
+
+### Ollama (default)
+```json
+{ "embedding": { "provider": "ollama", "model": "nomic-embed-text", "dimensions": 768 } }
+```
+
+### Local (sentence-transformers, no network)
+```bash
+uv sync --extra local
+```
+```json
+{ "embedding": { "provider": "local" } }
+```
+
+### OpenAI-compat (OpenRouter, OpenAI, Cohere compat, etc.)
+
+**OpenRouter:**
+```json
+{
+  "embedding": {
+    "provider": "compat",
+    "api_type": "openrouter",
+    "api_endpoint": "https://openrouter.ai/api/v1",
+    "model": "openai/text-embedding-3-small",
+    "dimensions": 1536
+  }
+}
+```
+
+**Cohere via OpenAI compat API:**
+```json
+{
+  "embedding": {
+    "provider": "compat",
+    "api_type": "cohere",
+    "api_endpoint": "https://api.cohere.com/compatibility/v1",
+    "model": "embed-english-light-v3.0",
+    "dimensions": 384
+  }
+}
+```
+
+Set `REMEMBLE_EMBEDDING__API_KEY` or `OPENROUTER_API_KEY` / `OPENAI_API_KEY` env var.
+
+## Development
+
+```bash
+make dev      # install deps
+make test     # run tests
+make check    # fmt + lint + test
+```

rememble-0.1.1/README.md

@@ -0,0 +1,103 @@
+# Rememble
+
+Local-first memory server with hybrid search, knowledge graph, and RAG context assembly.
+
+SQLite + sqlite-vec + FTS5 backend. Works with any MCP client.
+
+## Features
+
+- Hybrid search: BM25 + vector KNN + temporal scoring (RRF fusion)
+- Knowledge graph: entities, observations, relations
+- Token-budgeted RAG context assembly
+- Multiple embedding providers: Ollama, local (sentence-transformers), OpenAI-compat
+
+## Install
+
+```bash
+uv sync
+```
+
+## MCP Client Setup
+
+### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "rememble": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/Rememble", "rememble"]
+    }
+  }
+}
+```
+
+## Configuration
+
+Config file: `~/.rememble/config.json` (auto-created on first run).
+
+All fields can be overridden via env vars with `REMEMBLE_` prefix and `__` as nested delimiter.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `REMEMBLE_DB_PATH` | `~/.rememble/memory.db` | SQLite database path |
+| `REMEMBLE_EMBEDDING__PROVIDER` | `ollama` | `ollama` \| `local` \| `compat` |
+| `REMEMBLE_EMBEDDING__MODEL` | `nomic-embed-text` | Model name for active provider |
+| `REMEMBLE_EMBEDDING__DIMENSIONS` | `768` | Embedding dimensions |
+| `REMEMBLE_EMBEDDING__OLLAMA_URL` | `http://localhost:11434` | Ollama base URL |
+| `REMEMBLE_EMBEDDING__API_TYPE` | `openrouter` | Label for compat provider (logging only) |
+| `REMEMBLE_EMBEDDING__API_ENDPOINT` | `https://openrouter.ai/api/v1` | OpenAI-compat base URL |
+| `REMEMBLE_EMBEDDING__API_KEY` | — | API key (or set `OPENROUTER_API_KEY` / `OPENAI_API_KEY`) |
+
+## Embedding Providers
+
+### Ollama (default)
+```json
+{ "embedding": { "provider": "ollama", "model": "nomic-embed-text", "dimensions": 768 } }
+```
+
+### Local (sentence-transformers, no network)
+```bash
+uv sync --extra local
+```
+```json
+{ "embedding": { "provider": "local" } }
+```
+
+### OpenAI-compat (OpenRouter, OpenAI, Cohere compat, etc.)
+
+**OpenRouter:**
+```json
+{
+  "embedding": {
+    "provider": "compat",
+    "api_type": "openrouter",
+    "api_endpoint": "https://openrouter.ai/api/v1",
+    "model": "openai/text-embedding-3-small",
+    "dimensions": 1536
+  }
+}
+```
+
+**Cohere via OpenAI compat API:**
+```json
+{
+  "embedding": {
+    "provider": "compat",
+    "api_type": "cohere",
+    "api_endpoint": "https://api.cohere.com/compatibility/v1",
+    "model": "embed-english-light-v3.0",
+    "dimensions": 384
+  }
+}
+```
+
+Set `REMEMBLE_EMBEDDING__API_KEY` or `OPENROUTER_API_KEY` / `OPENAI_API_KEY` env var.
+
+## Development
+
+```bash
+make dev      # install deps
+make test     # run tests
+make check    # fmt + lint + test
+```

rememble-0.1.1/docker-compose.yml

@@ -0,0 +1,6 @@
+services:
+  rememble:
+    build: .
+    stdin_open: true
+    volumes:
+      - ~/.rememble:/data

rememble-0.1.1/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "rememble"
+version = "0.1.1"
+description = "Local MCP memory server with hybrid search, knowledge graph, and RAG"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Nik Cubrilovic", email = "git@nikcub.me" }]
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0",
+    "sqlite-vec>=0.1.6",
+    "tiktoken>=0.8",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+local = ["sentence-transformers>=3.0", "onnxruntime>=1.19"]
+all = ["rememble[local]"]
+
+[project.scripts]
+rememble = "rememble.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rememble"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "basedpyright>=1.20",
+    "ruff>=0.8",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.basedpyright]
+pythonVersion = "3.11"
+typeCheckingMode = "standard"
+reportCallIssue = "warning"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

rememble-0.1.1/rememble/__init__.py

@@ -0,0 +1,5 @@
+"""Rememble — local memory server with hybrid search and knowledge graph."""
+
+from rememble.version import __version__
+
+__all__ = ["__version__"]

rememble-0.1.1/rememble/config.py

@@ -0,0 +1,72 @@
+"""Config loading from ~/.rememble/config.json with env var overrides."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+CONFIG_DIR = Path.home() / ".rememble"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+class EmbeddingConfig(BaseModel):
+    provider: str = "ollama"
+    model: str = "nomic-embed-text"
+    dimensions: int = 768
+    ollama_url: str = "http://localhost:11434"
+    # OpenAI-compat settings (provider="compat")
+    api_type: str = "openrouter"  # label only: openai | openrouter | cohere | etc.
+    api_endpoint: str = "https://openrouter.ai/api/v1"
+    api_key: str | None = None
+    # Local settings
+    local_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    local_backend: Literal["torch", "onnx", "openvino"] = "onnx"
+
+
+class SearchConfig(BaseModel):
+    default_limit: int = 10
+    rrf_k: int = 60
+    bm25_weight: float = 0.4
+    vector_weight: float = 0.5
+    temporal_weight: float = 0.1
+    recency_half_life_days: float = 7.0
+
+
+class RAGConfig(BaseModel):
+    max_context_tokens: int = 1500
+    max_snippets: int = 24
+    snippet_max_tokens: int = 200
+    expansion_max_tokens: int = 600
+
+
+class ChunkingConfig(BaseModel):
+    target_tokens: int = 400
+    overlap_tokens: int = 40
+
+
+class RemembleConfig(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="REMEMBLE_",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+    db_path: str = Field(default_factory=lambda: str(CONFIG_DIR / "memory.db"))
+    embedding: EmbeddingConfig = Field(default_factory=EmbeddingConfig)
+    search: SearchConfig = Field(default_factory=SearchConfig)
+    rag: RAGConfig = Field(default_factory=RAGConfig)
+    chunking: ChunkingConfig = Field(default_factory=ChunkingConfig)
+
+
+def loadConfig() -> RemembleConfig:
+    """Load config from ~/.rememble/config.json with env var overrides."""
+    if CONFIG_PATH.exists():
+        raw = json.loads(CONFIG_PATH.read_text())
+        return RemembleConfig(**raw)
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    config = RemembleConfig()
+    CONFIG_PATH.write_text(config.model_dump_json(indent=2))
+    return config