memkernel 0.2.0__py3-none-any.whl

memkernel/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""MemKernel — Code-aware memory server for AI coding copilots."""
+
+__version__ = "0.2.0"

memkernel/api/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0

memkernel/api/app.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""FastAPI admin API factory and entry point.
+
+Production:
+    uvicorn memkernel.api.app:app --reload
+
+Tests inject a pre-built MemoryService via create_app(memory_service=svc).
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from memkernel.core.services import MemoryService
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(memory_service: MemoryService | None = None) -> FastAPI:
+    """FastAPI app factory.
+
+    Tests pass a pre-built MemoryService (with EphemeralClient, MockEmbedding).
+    Production calls with None — MemoryService is built from env at startup.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        if memory_service is not None:
+            app.state.memory_service = memory_service
+        else:
+            app.state.memory_service = _build_service()
+            logger.info("MemoryService initialised for project %s", app.state.memory_service.project_id)
+        yield
+
+    application: FastAPI = FastAPI(
+        title="MemKernel Admin API",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    from memkernel.api.routes.admin import router
+
+    application.include_router(router)
+    return application
+
+
+def _build_service() -> MemoryService:
+    """Construct MemoryService from environment settings (production only)."""
+    from memkernel.factory import build_service
+
+    return build_service()
+
+
+# Module-level app for `uvicorn memkernel.api.app:app`
+# MemoryService is built lazily in the lifespan — safe to import without real deps.
+app = create_app()

memkernel/api/routes/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0

memkernel/api/routes/admin.py

@@ -0,0 +1,44 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""Admin API route handlers: /health, /stats, /collections."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, Request
+
+if TYPE_CHECKING:
+    from memkernel.core.services import MemoryService
+
+router = APIRouter()
+
+
+def _svc(request: Request) -> MemoryService:
+    return request.app.state.memory_service  # type: ignore[no-any-return]
+
+
+@router.get("/health")
+async def health(request: Request) -> dict[str, Any]:
+    """Server liveness check: status, collection count, memory count."""
+    svc = _svc(request)
+    return {
+        "status": "ok",
+        "project_id": svc.project_id,
+        "collection_count": svc.collection_count(),
+        "memory_count": svc.count(),
+    }
+
+
+@router.get("/stats")
+async def stats(request: Request) -> dict[str, Any]:
+    """Memory metrics: per-type breakdown, growth by time window, last recall latency."""
+    svc = _svc(request)
+    return svc.stats()
+
+
+@router.get("/collections")
+async def collections(request: Request) -> list[dict[str, Any]]:
+    """List all project collections with record counts."""
+    svc = _svc(request)
+    return svc.list_collections()

memkernel/config.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""MemKernel configuration via environment variables."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class MemKernelSettings(BaseSettings):
+    """All settings are configurable via MEMKERNEL_ prefixed env vars."""
+
+    model_config = SettingsConfigDict(env_prefix="MEMKERNEL_", env_file=".env")
+
+    project_id: str = "default"
+    default_session_id: str = "default"
+
+    # ChromaDB
+    chroma_persist_path: str = ".memkernel/chroma"
+    chroma_collection_prefix: str = "memkernel"
+
+    # Embedding
+    embedding_model: str = "all-MiniLM-L6-v2"
+    embedding_dimension: int = 384
+
+    # Retrieval
+    search_top_k: int = 5
+    rrf_k: int = 60
+    preview_length: int = 200
+
+    # Chunking
+    chunk_size: int = 1500  # max chars per chunk
+    chunk_overlap: int = 200  # char overlap between token chunks (fallback only)
+
+    # Lifecycle / decay (see docs/architecture/memory-tiers.md)
+    episode_ttl_days: int = 30  # base TTL for short-term `episode` memories
+    observation_ttl_days: int = 7  # base TTL for short-term `observation` memories
+    task_ttl_hours: int = 24  # base TTL for working-memory `task` records
+    access_boost: float = 0.5  # each recall extends TTL by this fraction of the base TTL
+    recency_half_life_days: float = 7.0  # recency decay half-life for short-term memories
+
+    # Recall scoring: final = w_relevance * fused + w_recency * recency + w_importance * importance
+    recall_weight_relevance: float = 1.0
+    recall_weight_recency: float = 0.3
+    recall_weight_importance: float = 0.3
+
+    # LLM wiki bridge: directory holding the markdown wiki (index.md, decisions/, ...).
+    # Empty = no wiki configured; wiki_export/wiki_import then require an explicit path.
+    wiki_dir: str = ""
+
+    # Server
+    transport: Literal["stdio", "streamable-http"] = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8765

memkernel/core/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0

memkernel/core/models.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""Domain models for MemKernel.
+
+Memory is organised in three tiers (see docs/architecture/memory-tiers.md):
+
+* ``working``    — the agent's scratchpad for the current task. Session-scoped,
+                   expires within hours. Cognitive analogue: working memory.
+* ``short_term`` — episodic memory: what happened, what was observed. Subject
+                   to decay; frequently recalled items survive longer.
+* ``long_term``  — semantic and procedural memory: decisions, conventions,
+                   facts, procedures, code understanding. Never expires; curated
+                   through consolidation and (optionally) an LLM wiki.
+
+Each :class:`MemoryType` belongs to exactly one tier (``TYPE_TIER``), so callers
+only choose a type; the tier, default importance and decay policy follow.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class MemoryTier(StrEnum):
+    """Lifecycle tier of a memory. Drives decay policy and recall weighting."""
+
+    WORKING = "working"
+    SHORT_TERM = "short_term"
+    LONG_TERM = "long_term"
+
+
+class MemoryType(StrEnum):
+    """Classification of stored memories. Determines tier, importance and TTL policy."""
+
+    # Long-term, semantic
+    DECISION = "decision"
+    CONVENTION = "convention"
+    FACT = "fact"
+    CODE = "code"
+    # Long-term, procedural
+    PROCEDURE = "procedure"
+    # Short-term, episodic
+    EPISODE = "episode"
+    OBSERVATION = "observation"
+    # Working memory
+    TASK = "task"
+
+
+TYPE_TIER: dict[MemoryType, MemoryTier] = {
+    MemoryType.DECISION: MemoryTier.LONG_TERM,
+    MemoryType.CONVENTION: MemoryTier.LONG_TERM,
+    MemoryType.FACT: MemoryTier.LONG_TERM,
+    MemoryType.CODE: MemoryTier.LONG_TERM,
+    MemoryType.PROCEDURE: MemoryTier.LONG_TERM,
+    MemoryType.EPISODE: MemoryTier.SHORT_TERM,
+    MemoryType.OBSERVATION: MemoryTier.SHORT_TERM,
+    MemoryType.TASK: MemoryTier.WORKING,
+}
+
+# Default importance (0..1) when the caller does not supply one.
+# Mirrors the "importance" axis of Generative Agents (Park et al., 2023):
+# durable, high-consequence knowledge scores high; raw observations score low.
+DEFAULT_IMPORTANCE: dict[MemoryType, float] = {
+    MemoryType.DECISION: 0.9,
+    MemoryType.CONVENTION: 0.9,
+    MemoryType.PROCEDURE: 0.8,
+    MemoryType.FACT: 0.7,
+    MemoryType.CODE: 0.6,
+    MemoryType.TASK: 0.5,
+    MemoryType.EPISODE: 0.4,
+    MemoryType.OBSERVATION: 0.3,
+}
+
+
+def tier_of(memory_type: MemoryType) -> MemoryTier:
+    """Return the tier a memory type belongs to."""
+    return TYPE_TIER[memory_type]
+
+
+class Memory(BaseModel):
+    """A stored unit of knowledge with full content and metadata."""
+
+    ref_id: str
+    content: str
+    type: MemoryType
+    project_id: str
+    session_id: str
+    timestamp: datetime
+    source: str = ""
+    content_hash: str
+    token_count: int
+    checkpoint: bool = False
+    chunk_refs: list[str] = []
+    # Tiered-memory metadata (all optional for backward compatibility with
+    # records written by memkernel 0.1.x, which carry none of these).
+    tier: MemoryTier = MemoryTier.LONG_TERM
+    importance: float = Field(default=0.5, ge=0.0, le=1.0)
+    access_count: int = 0
+    last_accessed: datetime | None = None
+    tags: list[str] = []
+    supersedes: str | None = None
+    promoted_from: str | None = None
+
+
+class ArtifactRef(BaseModel):
+    """Lightweight reference returned by recall — no full content.
+
+    Matches spec FR-003: ref_id, preview, score, token_count, type, timestamp.
+    No checkpoint field — checkpoint filtering is query-side via checkpoint_only param.
+    ``tier`` and ``importance`` are included so the caller can see why a result
+    ranked where it did without a second round trip.
+    """
+
+    ref_id: str
+    preview: str
+    score: float
+    token_count: int
+    type: MemoryType
+    timestamp: datetime
+    tier: MemoryTier = MemoryTier.LONG_TERM
+    importance: float = 0.5
+
+
+class SearchResult(BaseModel):
+    """Internal pre-fusion search result from a single source."""
+
+    ref_id: str
+    score: float
+    rank: int
+
+
+class SearchQuery(BaseModel):
+    """Internal query representation for HybridSearchService."""
+
+    query_text: str
+    type_filter: MemoryType | None = None
+    tier_filter: MemoryTier | None = None
+    session_id_filter: str | None = None
+    checkpoint_only: bool = False
+    top_k: int = 5

memkernel/core/ports.py

@@ -0,0 +1,95 @@
+# Copyright (c) 2026 EGOGE
+# SPDX-License-Identifier: Apache-2.0
+"""Protocol definitions for MemKernel adapters.
+
+Domain logic in core/ depends ONLY on these protocols.
+Concrete implementations live in storage/, retrieval/, etc.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from memkernel.core.models import Memory, SearchResult
+
+
+@runtime_checkable
+class VectorStorePort(Protocol):
+    """Dense vector store backend (ChromaDB for MVP)."""
+
+    def upsert(
+        self,
+        ref_id: str,
+        content: str,
+        embedding: list[float],
+        metadata: dict[str, Any],
+    ) -> None: ...
+
+    def search_dense(
+        self,
+        query_embedding: list[float],
+        top_k: int,
+        where: dict[str, Any] | None = None,
+    ) -> list[SearchResult]: ...
+
+    def get_by_id(self, ref_id: str) -> Memory | None: ...
+
+    def delete(self, ref_id: str) -> bool: ...
+
+    def list_all(self, where: dict[str, Any] | None = None) -> list[Memory]: ...
+
+    def find_by_hash(self, content_hash: str, memory_type: str) -> Memory | None:
+        """Find by content_hash + type (dedup key per ADR-5)."""
+        ...
+
+    def update_metadata(self, ref_id: str, metadata: dict[str, Any]) -> None:
+        """Fetch-and-merge: only overwrites caller-specified keys."""
+        ...
+
+    def count(self) -> int: ...
+
+    def list_collections(self) -> list[dict[str, Any]]:
+        """List all collections visible to this adapter with their record counts."""
+        ...
+
+
+@runtime_checkable
+class EmbeddingPort(Protocol):
+    """Text embedding model."""
+
+    def embed(self, texts: list[str]) -> list[list[float]]: ...
+
+    @property
+    def dimension(self) -> int: ...
+
+
+@runtime_checkable
+class SparseIndexPort(Protocol):
+    """BM25 sparse search index."""
+
+    def add(self, ref_id: str, content: str) -> None: ...
+
+    def remove(self, ref_id: str) -> None: ...
+
+    def search(self, query: str, top_k: int) -> list[SearchResult]: ...
+
+    def search_all(self, query: str) -> list[SearchResult]:
+        """Score entire corpus, return all results with score > 0."""
+        ...
+
+    def rebuild(self, documents: list[tuple[str, str]]) -> None: ...
+
+    @property
+    def needs_rebuild(self) -> bool: ...
+
+    def mark_needs_rebuild(self) -> None: ...
+
+    def __len__(self) -> int: ...
+
+
+@runtime_checkable
+class ChunkerPort(Protocol):
+    """Code/text chunking strategy (stub for future US3)."""
+
+    def chunk(self, content: str, metadata: dict[str, Any]) -> list[str]: ...