feat(storage): add SQLite vector store, VectorStore protocol, and tests

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.venv/

README.md

@@ -0,0 +1,21 @@
+# MemoMind
+
+MemoMind is a local-first starter kit for building a multimodal personal knowledge agent. It provides a minimal set of Python modules for ingesting content, representing memories, and querying vector stores.
+
+## Quick start
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Project layout
+
+- `src/memomind` - core package
+- `docs` - specifications and architecture notes
+
+## Storage options
+
+- `InMemoryVectorStore` for prototyping.
+- `SqliteVectorStore` for local persistence.

docs/ARCHITECTURE.md

@@ -0,0 +1,14 @@
+# MemoMind Architecture (Draft)
+
+## Components
+- `core.agent`: orchestrates ingestion, retrieval, and LLM calls.
+- `core.memory`: manages short/long-term memory stores.
+- `storage.vector_store`: in-memory similarity search.
+- `storage.sqlite_store`: SQLite-backed vector persistence.
+- `llm`: pluggable LLM and embedding clients.
+
+## Data Flow
+1. Raw input -> `models.Document`
+2. Document -> embeddings via `llm.embeddings`
+3. Embeddings -> `storage.vector_store` or `storage.sqlite_store`
+4. Retrieval results -> `core.agent` response

docs/SPEC.md

@@ -0,0 +1,12 @@
+# MemoMind Specification (Draft)
+
+## Goals
+- Collect multimodal data (text, image, audio, structured) into a personal knowledge base.
+- Provide short/long-term memory with retrieval for Q&A.
+- Run locally with optional pluggable LLM backends.
+
+## MVP Scope
+- Text ingestion pipeline.
+- Memory data models (document, memory, message).
+- In-memory or SQLite-backed vector search interface.
+- Simple agent orchestrator for storing and retrieving memories.

pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "memomind"
+version = "0.1.0"
+description = "Local-first multimodal memory agent starter"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Project-Test Contributors" }
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/memomind/__init__.py

@@ -0,0 +1,9 @@
+"""MemoMind core package."""
+
+from memomind.core.agent import MemoAgent
+from memomind.core.memory import MemoryStore
+from memomind.models.document import Document
+from memomind.models.memory import Memory
+from memomind.models.message import Message
+
+__all__ = ["Document", "Memory", "Message", "MemoryStore", "MemoAgent"]

src/memomind/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration helpers."""
+
+from memomind.config.settings import Settings
+
+__all__ = ["Settings"]

src/memomind/config/settings.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime configuration for MemoMind."""
+
+    embedding_model: str = "local-embedding"
+    llm_model: str = "local-llm"
+    max_context_messages: int = 12

src/memomind/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core orchestration modules."""
+
+from memomind.core.agent import MemoAgent
+from memomind.core.memory import MemoryStore
+
+__all__ = ["MemoAgent", "MemoryStore"]

src/memomind/core/agent.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from memomind.config.settings import Settings
+from memomind.core.knowledge import KnowledgeBase
+from memomind.core.memory import MemoryStore
+from memomind.llm.client import LlmClient
+from memomind.llm.embeddings import EmbeddingClient
+from memomind.models.document import Document
+from memomind.models.memory import Memory
+
+
+@dataclass
+class MemoAgent:
+    """Coordinates ingestion, memory storage, and retrieval."""
+
+    settings: Settings = field(default_factory=Settings)
+    knowledge_base: KnowledgeBase = field(default_factory=KnowledgeBase)
+    memory_store: MemoryStore = field(default_factory=MemoryStore)
+    llm_client: LlmClient = field(default_factory=LlmClient)
+    embedding_client: EmbeddingClient = field(default_factory=EmbeddingClient)
+
+    def ingest(self, document: Document) -> None:
+        embedding = self.embedding_client.embed(document.content)
+        enriched = Document(
+            content=document.content,
+            source=document.source,
+            created_at=document.created_at,
+            metadata=document.metadata,
+            tags=document.tags,
+            embedding=embedding,
+        )
+        self.knowledge_base.add(enriched)
+
+    def remember(self, memory_id: str, memory: Memory) -> None:
+        embedding = self.embedding_client.embed(memory.summary)
+        self.memory_store.add_memory(memory_id, memory, embedding=embedding)
+
+    def recall(self, query: str, limit: int = 5) -> List[Memory]:
+        embedding = self.embedding_client.embed(query)
+        return list(self.memory_store.search(embedding, limit=limit))
+
+    def answer(self, query: str) -> Optional[str]:
+        memories = self.recall(query)
+        if not memories:
+            return None
+        context = "\n".join(memory.summary for memory in memories)
+        prompt = f"Use the following memories to answer the question:\n{context}\nQuestion: {query}"
+        return self.llm_client.complete(prompt)

src/memomind/core/knowledge.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from memomind.models.document import Document
+
+
+@dataclass
+class KnowledgeBase:
+    """Tracks ingested documents for later processing."""
+
+    documents: List[Document] = field(default_factory=list)
+
+    def add(self, document: Document) -> None:
+        self.documents.append(document)
+
+    def list_sources(self) -> List[str]:
+        return [doc.source for doc in self.documents]

src/memomind/core/memory.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional
+
+from memomind.models.memory import Memory
+from memomind.storage.base import VectorStore
+from memomind.storage.vector_store import InMemoryVectorStore
+
+
+@dataclass
+class MemoryStore:
+    """Manages short and long-term memory collections."""
+
+    vector_store: VectorStore = field(default_factory=InMemoryVectorStore)
+    memories: Dict[str, Memory] = field(default_factory=dict)
+
+    def add_memory(self, memory_id: str, memory: Memory, embedding: Optional[List[float]] = None) -> None:
+        self.memories[memory_id] = memory
+        if embedding is not None:
+            self.vector_store.upsert(memory_id, embedding, payload={"summary": memory.summary})
+
+    def get_memory(self, memory_id: str) -> Optional[Memory]:
+        return self.memories.get(memory_id)
+
+    def search(self, embedding: List[float], limit: int = 5) -> Iterable[Memory]:
+        results = self.vector_store.search(embedding, limit=limit)
+        for memory_id, _score in results:
+            memory = self.memories.get(memory_id)
+            if memory:
+                yield memory

src/memomind/llm/__init__.py

@@ -0,0 +1,6 @@
+"""LLM integrations."""
+
+from memomind.llm.client import LlmClient
+from memomind.llm.embeddings import EmbeddingClient
+
+__all__ = ["LlmClient", "EmbeddingClient"]

src/memomind/llm/client.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class LlmClient:
+    """Placeholder LLM client implementation."""
+
+    model: str = "local-llm"
+
+    def complete(self, prompt: str) -> str:
+        return f"[stubbed response from {self.model}] {prompt}"

src/memomind/llm/embeddings.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+
+@dataclass
+class EmbeddingClient:
+    """Placeholder embedding client implementation."""
+
+    model: str = "local-embedding"
+
+    def embed(self, text: str) -> List[float]:
+        if not text:
+            return [0.0]
+        return [float(sum(bytearray(text, "utf-8")) % 997) / 997.0]

src/memomind/models/__init__.py

@@ -0,0 +1,7 @@
+"""Data models for MemoMind."""
+
+from memomind.models.document import Document
+from memomind.models.memory import Memory
+from memomind.models.message import Message
+
+__all__ = ["Document", "Memory", "Message"]

src/memomind/models/document.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Document:
+    """Raw content ingested into the system."""
+
+    content: str
+    source: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    tags: List[str] = field(default_factory=list)
+    embedding: Optional[List[float]] = None

src/memomind/models/memory.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+
+@dataclass(frozen=True)
+class Memory:
+    """Normalized memory representation stored for retrieval."""
+
+    summary: str
+    memory_type: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    importance: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    related_document_id: Optional[str] = None

src/memomind/models/message.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict
+
+
+@dataclass(frozen=True)
+class Message:
+    """Conversation message for working memory context."""
+
+    role: str
+    content: str
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    metadata: Dict[str, str] = field(default_factory=dict)

src/memomind/storage/__init__.py

@@ -0,0 +1,7 @@
+"""Storage backends."""
+
+from memomind.storage.base import VectorStore
+from memomind.storage.sqlite_store import SqliteVectorStore
+from memomind.storage.vector_store import InMemoryVectorStore
+
+__all__ = ["InMemoryVectorStore", "SqliteVectorStore", "VectorStore"]

src/memomind/storage/base.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Dict, List, Protocol, Tuple
+
+
+class VectorStore(Protocol):
+    """Protocol for vector storage backends."""
+
+    def upsert(self, item_id: str, vector: List[float], payload: Dict[str, str]) -> None:
+        ...
+
+    def search(self, vector: List[float], limit: int = 5) -> List[Tuple[str, float]]:
+        ...

src/memomind/storage/serialization.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+
+def dumps_vector(vector: List[float]) -> str:
+    return json.dumps(vector)
+
+
+def loads_vector(value: str) -> List[float]:
+    return [float(item) for item in json.loads(value)]
+
+
+def dumps_payload(payload: Dict[str, str]) -> str:
+    return json.dumps(payload)
+
+
+def loads_payload(value: str) -> Dict[str, str]:
+    return {str(key): str(val) for key, val in json.loads(value).items()}