engramkit 0.1.1__py3-none-any.whl

engramkit/__init__.py

@@ -0,0 +1,8 @@
+"""EngramKit — AI memory system with hybrid search, git-aware ingestion, and garbage collection."""
+
+import logging
+
+# ChromaDB 0.6.x has a buggy Posthog telemetry client — silence it
+logging.getLogger("chromadb.telemetry.product.posthog").setLevel(logging.CRITICAL)
+
+__version__ = "0.1.0"

engramkit/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m engramkit"""
+from engramkit.cli import main
+
+main()

engramkit/api/helpers.py

@@ -0,0 +1,85 @@
+"""Shared helpers and request models for API routes."""
+
+from typing import Optional
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+from engramkit.config import ENGRAMKIT_HOME
+from engramkit.storage.vault import Vault
+from engramkit.graph.knowledge_graph import KnowledgeGraph
+
+
+def get_vault_by_id(vault_id: str) -> Vault:
+    vault_path = ENGRAMKIT_HOME / "vaults" / vault_id
+    if not vault_path.exists():
+        raise HTTPException(404, f"Vault {vault_id} not found")
+    vault = Vault(vault_path)
+    vault.open()
+    return vault
+
+
+def get_kg(vault: Vault) -> KnowledgeGraph:
+    return KnowledgeGraph(str(vault.vault_path / "knowledge_graph.sqlite3"))
+
+
+# ── Request Models ────────────────────────────────────────────────────────
+
+class CreateVaultRequest(BaseModel):
+    repo_path: str
+
+class SearchRequest(BaseModel):
+    query: str
+    wing: Optional[str] = None
+    room: Optional[str] = None
+    n_results: int = 5
+
+class MineRequest(BaseModel):
+    wing: Optional[str] = None
+    room: str = "general"
+    full: bool = False
+    dry_run: bool = False
+
+class GCRequest(BaseModel):
+    retention_days: int = 30
+    dry_run: bool = False
+
+class SaveRequest(BaseModel):
+    content: str
+    wing: Optional[str] = None
+    room: str = "general"
+    importance: float = 3.0
+
+class DiaryRequest(BaseModel):
+    content: str
+    wing: str = "diary"
+
+class AddTripleRequest(BaseModel):
+    subject: str
+    predicate: str
+    object: str
+    valid_from: Optional[str] = None
+    valid_to: Optional[str] = None
+    confidence: float = 1.0
+
+class InvalidateRequest(BaseModel):
+    subject: str
+    predicate: str
+    object: str
+    ended: Optional[str] = None
+
+class UpdateChunkRequest(BaseModel):
+    importance: Optional[float] = None
+
+class ConfigUpdateRequest(BaseModel):
+    key: str
+    value: str
+
+class ChatRequest(BaseModel):
+    message: str
+    mode: str = "rag"             # "rag" = EngramKit search + Claude, "direct" = Claude only (no RAG)
+    vault_id: Optional[str] = None
+    vault_ids: Optional[list] = None
+    n_context: int = 10
+    model: str = "claude-sonnet-4-20250514"
+    history: list = []
+    pinned_chunks: list = []

engramkit/api/routes_chat.py

@@ -0,0 +1,183 @@
+"""RAG chat endpoint — search vault + stream via Claude Agent SDK."""
+
+import json
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from engramkit.search.hybrid import hybrid_search
+from engramkit.api.helpers import get_vault_by_id, ChatRequest
+
+router = APIRouter(prefix="/api", tags=["chat"])
+
+
+def _format_history(history: list) -> str:
+    """Format conversation history for the prompt."""
+    if not history:
+        return ""
+    lines = ["## Conversation History:"]
+    for h in history[-10:]:  # last 10 messages
+        role = h.get("role", "user")
+        content = h.get("content", "")[:500]  # truncate long messages
+        lines.append(f"**{role}:** {content}")
+    lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def _extract_usage(msg):
+    """Extract token counts from ResultMessage."""
+    input_tokens = output_tokens = cache_read = 0
+    msg_usage = getattr(msg, 'usage', None)
+    if isinstance(msg_usage, dict):
+        input_tokens = msg_usage.get('input_tokens', 0) or 0
+        output_tokens = msg_usage.get('output_tokens', 0) or 0
+        cache_read = msg_usage.get('cache_read_input_tokens', 0) or 0
+    if input_tokens == 0:
+        for md in (getattr(msg, 'model_usage', None) or {}).values():
+            if isinstance(md, dict):
+                input_tokens += md.get('inputTokens', 0) or 0
+                output_tokens += md.get('outputTokens', 0) or 0
+                cache_read += md.get('cacheReadInputTokens', 0) or 0
+    return input_tokens, output_tokens, cache_read
+
+
+@router.post("/chat")
+async def chat(req: ChatRequest):
+    # 1. Resolve vault IDs + repo paths
+    vault_ids = req.vault_ids or ([req.vault_id] if req.vault_id else [])
+    if not vault_ids:
+        raise HTTPException(400, "No vault selected")
+
+    repo_names = []
+    repo_paths = []
+    for vid in vault_ids:
+        vault = get_vault_by_id(vid)
+        try:
+            rp = vault.get_meta("repo_path", "unknown")
+            repo_names.append(rp.split("/")[-1] if rp else vid)
+            if rp: repo_paths.append(rp)
+        finally:
+            vault.close()
+
+    repo_name = ", ".join(repo_names)
+
+    # 2. Build prompt based on mode
+    results = []
+    if req.mode == "rag":
+        # Search across vaults
+        for vid in vault_ids:
+            vault = get_vault_by_id(vid)
+            try:
+                hits = hybrid_search(req.message, vault, n_results=req.n_context)
+                rp = vault.get_meta("repo_path", "unknown")
+                rn = rp.split("/")[-1] if rp else vid
+                for r in hits: r["_repo"] = rn
+                results.extend(hits)
+            finally:
+                vault.close()
+
+        results.sort(key=lambda x: x.get("score", 0), reverse=True)
+        results = results[:req.n_context]
+
+        context_chunks = [
+            f"[{r.get('_repo', '')}/{r['file_path']}] (score: {r['score']:.4f})\n{r['content']}"
+            for r in results
+        ]
+        context = "\n\n---\n\n".join(context_chunks) if context_chunks else "No relevant context."
+
+        pinned = ""
+        if req.pinned_chunks:
+            pinned = "\n\n---\n\n".join(f"[{pc.get('file','?')}] (pinned)\n{pc.get('content','')}" for pc in req.pinned_chunks)
+
+        full_context = f"## Pinned:\n{pinned}\n\n## Auto-Retrieved:\n{context}" if pinned else context
+
+        prompt = f"""You are a code assistant for the "{repo_name}" codebase.
+
+RULES:
+1. Answer PRIMARILY from the pre-searched code chunks below
+2. Only use Read/Grep if chunks clearly don't contain the answer (max 2-3 tool calls)
+3. Do NOT explore the entire codebase — be focused
+4. Reference specific file paths
+5. Be concise
+
+## Pre-Searched Code Chunks:
+{full_context}
+
+{_format_history(req.history)}## Question:
+{req.message}"""
+
+    else:
+        # Direct mode — no RAG, just Claude + tools
+        prompt = f"""You are a code assistant for the "{repo_name}" codebase.
+
+Answer the question using your tools (Read, Grep, Glob). Be concise.
+
+{_format_history(req.history)}## Question:
+{req.message}"""
+
+    # 3. Stream response
+    async def generate():
+        try:
+            from claude_agent_sdk import (
+                query as sdk_query, ClaudeAgentOptions,
+                AssistantMessage, TextBlock, ToolUseBlock, ResultMessage, StreamEvent,
+            )
+        except ImportError:
+            yield f"data: {json.dumps({'type': 'text', 'text': 'Error: chat feature requires the [chat] extra. Install with: pip install engramkit[chat]'})}\n\n"
+            yield f"data: {json.dumps({'type': 'done'})}\n\n"
+            return
+
+        # Send mode indicator
+        yield f"data: {json.dumps({'type': 'mode', 'mode': req.mode})}\n\n"
+
+        # Send sources (only in RAG mode)
+        if results:
+            sources = [{
+                "file": r.get("file_path", "?"), "score": r.get("score", 0),
+                "content": r.get("content", ""), "wing": r.get("wing", ""),
+                "room": r.get("room", ""), "content_hash": r.get("content_hash", ""),
+            } for r in results]
+            yield f"data: {json.dumps({'type': 'sources', 'sources': sources})}\n\n"
+
+        got_content = False
+        tool_calls = 0
+
+        try:
+            async for msg in sdk_query(
+                prompt=prompt,
+                options=ClaudeAgentOptions(
+                    max_turns=None,
+                    permission_mode="auto",
+                    model=req.model or None,
+                    include_partial_messages=True,
+                    cwd=repo_paths[0] if repo_paths else None,
+                ),
+            ):
+                if isinstance(msg, StreamEvent):
+                    event = msg.event if hasattr(msg, 'event') else {}
+                    if isinstance(event, dict) and event.get("type") == "content_block_delta":
+                        delta = event.get("delta", {})
+                        if delta.get("type") == "text_delta" and delta.get("text"):
+                            got_content = True
+                            yield f"data: {json.dumps({'type': 'text', 'text': delta['text']})}\n\n"
+
+                elif isinstance(msg, AssistantMessage):
+                    for block in msg.content:
+                        if isinstance(block, ToolUseBlock):
+                            tool_calls += 1
+                            yield f"data: {json.dumps({'type': 'tool_call', 'tool': block.name, 'count': tool_calls})}\n\n"
+                        elif isinstance(block, TextBlock) and block.text and not got_content:
+                            got_content = True
+                            yield f"data: {json.dumps({'type': 'text', 'text': block.text})}\n\n"
+
+                elif isinstance(msg, ResultMessage):
+                    if not got_content and msg.result:
+                        yield f"data: {json.dumps({'type': 'text', 'text': msg.result})}\n\n"
+                    input_tokens, output_tokens, cache_read = _extract_usage(msg)
+                    yield f"data: {json.dumps({'type': 'usage', 'mode': req.mode, 'total_cost_usd': getattr(msg, 'total_cost_usd', 0) or 0, 'duration_ms': getattr(msg, 'duration_ms', 0) or 0, 'tool_calls': tool_calls, 'num_turns': getattr(msg, 'num_turns', 0) or 0, 'input_tokens': input_tokens, 'output_tokens': output_tokens, 'cache_read_tokens': cache_read})}\n\n"
+
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'text', 'text': f'Error: {str(e)}'})}\n\n"
+
+        yield f"data: {json.dumps({'type': 'done'})}\n\n"
+
+    return StreamingResponse(generate(), media_type="text/event-stream")

engramkit/api/routes_kg.py

@@ -0,0 +1,116 @@
+"""Knowledge graph endpoints."""
+
+from typing import Optional
+from fastapi import APIRouter
+
+from engramkit.api.helpers import get_vault_by_id, get_kg, AddTripleRequest, InvalidateRequest
+from engramkit.storage.gc import run_gc as _run_gc
+from engramkit.api.helpers import GCRequest
+
+router = APIRouter(prefix="/api", tags=["knowledge-graph"])
+
+
+@router.get("/vaults/{vault_id}/kg/stats")
+def kg_stats(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault); s = kg.stats(); kg.close(); return s
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/kg/entities")
+def kg_entities(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault)
+        rows = kg.conn.execute("SELECT * FROM entities ORDER BY name").fetchall()
+        kg.close(); return [dict(r) for r in rows]
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/kg/entity/{name}")
+def kg_entity(vault_id: str, name: str, as_of: Optional[str] = None, direction: str = "both"):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault)
+        facts = kg.query_entity(name, as_of=as_of, direction=direction)
+        kg.close(); return {"entity": name, "facts": facts, "count": len(facts)}
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/kg/timeline")
+def kg_timeline(vault_id: str, entity: Optional[str] = None):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault); t = kg.timeline(entity); kg.close()
+        return {"timeline": t, "count": len(t)}
+    finally:
+        vault.close()
+
+
+@router.post("/vaults/{vault_id}/kg/triples")
+def kg_add(vault_id: str, req: AddTripleRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault)
+        tid = kg.add_triple(req.subject, req.predicate, req.object,
+                            valid_from=req.valid_from, valid_to=req.valid_to, confidence=req.confidence)
+        kg.close(); return {"added": True, "triple_id": tid}
+    finally:
+        vault.close()
+
+
+@router.patch("/vaults/{vault_id}/kg/triples/invalidate")
+def kg_invalidate(vault_id: str, req: InvalidateRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault)
+        kg.invalidate(req.subject, req.predicate, req.object, ended=req.ended)
+        kg.close(); return {"invalidated": True}
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/kg/graph")
+def kg_graph(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        kg = get_kg(vault)
+        entities = kg.conn.execute("SELECT id, name, type FROM entities").fetchall()
+        triples = kg.conn.execute(
+            """SELECT s.name as source, t.predicate, o.name as target, t.valid_to
+               FROM triples t JOIN entities s ON t.subject=s.id JOIN entities o ON t.object=o.id"""
+        ).fetchall()
+        kg.close()
+        return {
+            "nodes": [{"id": r["id"], "name": r["name"], "type": r["type"]} for r in entities],
+            "edges": [{"source": r["source"], "target": r["target"], "predicate": r["predicate"],
+                       "current": r["valid_to"] is None} for r in triples],
+        }
+    finally:
+        vault.close()
+
+
+# ── GC ────────────────────────────────────────────────────────────────────
+
+@router.post("/vaults/{vault_id}/gc")
+def gc_vault(vault_id: str, req: GCRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        _run_gc(vault, dry_run=req.dry_run, retention_days=req.retention_days)
+        return {"completed": True, "dry_run": req.dry_run}
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/gc/log")
+def gc_log(vault_id: str, limit: int = 100):
+    vault = get_vault_by_id(vault_id)
+    try:
+        rows = vault.conn.execute("SELECT * FROM gc_log ORDER BY performed_at DESC LIMIT ?", (limit,)).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        vault.close()

engramkit/api/routes_memory.py

@@ -0,0 +1,112 @@
+"""Memory, save, diary, config, and hooks endpoints."""
+
+from typing import Optional
+from fastapi import APIRouter, HTTPException
+
+from engramkit.memory.layers import MemoryStack
+from engramkit.memory.token_budget import TokenBudget, count_tokens
+from engramkit.ingest.chunker import content_hash
+from engramkit.api.helpers import get_vault_by_id, SaveRequest, DiaryRequest, ConfigUpdateRequest
+
+router = APIRouter(prefix="/api", tags=["memory"])
+
+
+@router.get("/vaults/{vault_id}/memory/wakeup")
+def memory_wakeup(vault_id: str, wing: Optional[str] = None, l1_tokens: int = 1000):
+    vault = get_vault_by_id(vault_id)
+    try:
+        stack = MemoryStack(vault, TokenBudget(l1_max=l1_tokens))
+        result = stack.wake_up(wing=wing)
+        return {
+            "context": result["text"], "total_tokens": result["total_tokens"],
+            "l0": {"tokens": result["l0_report"].tokens_used, "budget": result["l0_report"].tokens_budget},
+            "l1": {"tokens": result["l1_report"].tokens_used, "budget": result["l1_report"].tokens_budget,
+                    "loaded": result["l1_report"].chunks_loaded, "deduped": result["l1_report"].chunks_skipped_dedup},
+        }
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/memory/recall")
+def memory_recall(vault_id: str, wing: Optional[str] = None, room: Optional[str] = None, n_results: int = 10):
+    vault = get_vault_by_id(vault_id)
+    try:
+        result = MemoryStack(vault).recall(wing=wing, room=room, n_results=n_results)
+        return {"text": result["text"], "tokens": result["report"].tokens_used, "chunks_loaded": result["report"].chunks_loaded}
+    finally:
+        vault.close()
+
+
+# ── Save & Diary ──────────────────────────────────────────────────────────
+
+@router.post("/vaults/{vault_id}/save")
+def save_content(vault_id: str, req: SaveRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        chash = content_hash(req.content)
+        wing = req.wing or vault.get_meta("wing") or "default"
+        vault.batch_upsert_chunks([{
+            "content_hash": chash, "content": req.content, "file_path": "manual_save", "file_hash": chash,
+            "wing": wing, "room": req.room, "generation": vault.current_generation(),
+            "importance": req.importance, "is_secret": 0,
+        }])
+        return {"saved": True, "content_hash": chash, "tokens": count_tokens(req.content)}
+    finally:
+        vault.close()
+
+
+@router.post("/vaults/{vault_id}/diary")
+def write_diary(vault_id: str, req: DiaryRequest):
+    from datetime import datetime
+    vault = get_vault_by_id(vault_id)
+    try:
+        entry = f"[{datetime.now().isoformat()}] {req.content}"
+        chash = content_hash(entry)
+        vault.batch_upsert_chunks([{
+            "content_hash": chash, "content": entry, "file_path": "diary", "file_hash": chash,
+            "wing": f"agent_{req.wing}", "room": "diary", "generation": vault.current_generation(),
+            "importance": 2.0, "is_secret": 0,
+        }])
+        return {"saved": True, "content_hash": chash}
+    finally:
+        vault.close()
+
+
+# ── Config & Hooks ────────────────────────────────────────────────────────
+
+@router.get("/config")
+def get_config():
+    from engramkit.config import DEFAULTS
+    return DEFAULTS
+
+
+@router.get("/vaults/{vault_id}/config")
+def get_vault_config(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        rows = vault.conn.execute("SELECT key, value FROM vault_meta").fetchall()
+        return {r["key"]: r["value"] for r in rows}
+    finally:
+        vault.close()
+
+
+@router.patch("/vaults/{vault_id}/config")
+def update_vault_config(vault_id: str, req: ConfigUpdateRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        vault.set_meta(req.key, req.value)
+        return {"set": True, "key": req.key, "value": req.value}
+    finally:
+        vault.close()
+
+
+@router.post("/vaults/{vault_id}/hooks/install")
+def install_hooks(vault_id: str):
+    from engramkit.hooks.git_hooks import install_hooks as _install
+    vault = get_vault_by_id(vault_id)
+    try:
+        repo_path = vault.get_meta("repo_path")
+        if not repo_path: raise HTTPException(400, "No repo_path")
+        _install(repo_path); return {"installed": True}
+    finally:
+        vault.close()

engramkit/api/routes_search.py

@@ -0,0 +1,50 @@
+"""Search and mining endpoints."""
+
+from fastapi import APIRouter, HTTPException
+
+from engramkit.storage.vault import VaultManager
+from engramkit.search.hybrid import hybrid_search
+from engramkit.api.helpers import get_vault_by_id, SearchRequest, MineRequest
+
+router = APIRouter(prefix="/api", tags=["search"])
+
+
+@router.post("/search")
+def global_search(req: SearchRequest):
+    all_results = []
+    for vault_info in VaultManager.list_vaults():
+        vault = get_vault_by_id(vault_info["vault_id"])
+        try:
+            results = hybrid_search(req.query, vault, req.n_results, req.wing, req.room)
+            for r in results:
+                r["vault_id"] = vault_info["vault_id"]
+                r["repo_path"] = vault_info["repo_path"]
+            all_results.extend(results)
+        finally:
+            vault.close()
+    all_results.sort(key=lambda x: x.get("score", 0), reverse=True)
+    return {"query": req.query, "results": all_results[:req.n_results], "count": len(all_results)}
+
+
+@router.post("/vaults/{vault_id}/search")
+def vault_search(vault_id: str, req: SearchRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        results = hybrid_search(req.query, vault, req.n_results, req.wing, req.room)
+        return {"query": req.query, "results": results, "count": len(results)}
+    finally:
+        vault.close()
+
+
+@router.post("/vaults/{vault_id}/mine")
+def mine_vault(vault_id: str, req: MineRequest):
+    from engramkit.ingest.pipeline import mine
+    vault = get_vault_by_id(vault_id)
+    repo_path = vault.get_meta("repo_path")
+    if not repo_path:
+        vault.close()
+        raise HTTPException(400, "No repo_path stored for this vault")
+    try:
+        return mine(repo_path, vault, wing=req.wing, room=req.room, full=req.full, dry_run=req.dry_run)
+    finally:
+        vault.close()

engramkit/api/routes_vaults.py

@@ -0,0 +1,110 @@
+"""Vault CRUD + files + chunks endpoints."""
+
+import shutil
+from typing import Optional
+from fastapi import APIRouter, HTTPException
+
+from engramkit.config import ENGRAMKIT_HOME
+from engramkit.storage.vault import VaultManager
+from engramkit.api.helpers import get_vault_by_id, CreateVaultRequest, UpdateChunkRequest
+
+router = APIRouter(prefix="/api", tags=["vaults"])
+
+
+@router.get("/vaults")
+def list_vaults():
+    return VaultManager.list_vaults()
+
+
+@router.post("/vaults")
+def create_vault(req: CreateVaultRequest):
+    vault = VaultManager.get_vault(req.repo_path)
+    vault_id = VaultManager.vault_id(req.repo_path)
+    stats = vault.stats()
+    vault.close()
+    return {"vault_id": vault_id, "repo_path": req.repo_path, **stats}
+
+
+@router.get("/vaults/{vault_id}")
+def get_vault(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        stats = vault.stats()
+        meta = {
+            "repo_path": vault.get_meta("repo_path", "unknown"),
+            "wing": vault.get_meta("wing"),
+            "last_commit": vault.get_meta("last_commit"),
+            "last_branch": vault.get_meta("last_branch"),
+        }
+        return {"vault_id": vault_id, **meta, **stats}
+    finally:
+        vault.close()
+
+
+@router.delete("/vaults/{vault_id}")
+def delete_vault(vault_id: str):
+    vault_path = ENGRAMKIT_HOME / "vaults" / vault_id
+    if not vault_path.exists():
+        raise HTTPException(404, "Vault not found")
+    shutil.rmtree(vault_path)
+    return {"deleted": True}
+
+
+# ── Files & Chunks ────────────────────────────────────────────────────────
+
+@router.get("/vaults/{vault_id}/files")
+def list_files(vault_id: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        rows = vault.conn.execute("SELECT * FROM files WHERE is_deleted = 0 ORDER BY file_path").fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/chunks")
+def list_chunks(
+    vault_id: str, wing: Optional[str] = None, room: Optional[str] = None,
+    is_stale: Optional[bool] = None, is_secret: Optional[bool] = None,
+    page: int = 1, per_page: int = 50,
+):
+    vault = get_vault_by_id(vault_id)
+    try:
+        sql, params = "SELECT * FROM chunks WHERE 1=1", []
+        if wing: sql += " AND wing = ?"; params.append(wing)
+        if room: sql += " AND room = ?"; params.append(room)
+        if is_stale is not None: sql += " AND is_stale = ?"; params.append(1 if is_stale else 0)
+        if is_secret is not None: sql += " AND is_secret = ?"; params.append(1 if is_secret else 0)
+
+        total = vault.conn.execute(sql.replace("SELECT *", "SELECT COUNT(*) as c"), params).fetchone()["c"]
+        sql += " ORDER BY updated_at DESC LIMIT ? OFFSET ?"
+        params.extend([per_page, (page - 1) * per_page])
+        rows = vault.conn.execute(sql, params).fetchall()
+
+        return {"chunks": [dict(r) for r in rows], "total": total, "page": page, "per_page": per_page,
+                "pages": (total + per_page - 1) // per_page}
+    finally:
+        vault.close()
+
+
+@router.get("/vaults/{vault_id}/chunks/{content_hash}")
+def get_chunk(vault_id: str, content_hash: str):
+    vault = get_vault_by_id(vault_id)
+    try:
+        row = vault.conn.execute("SELECT * FROM chunks WHERE content_hash = ?", (content_hash,)).fetchone()
+        if not row: raise HTTPException(404, "Chunk not found")
+        return dict(row)
+    finally:
+        vault.close()
+
+
+@router.patch("/vaults/{vault_id}/chunks/{content_hash}")
+def update_chunk(vault_id: str, content_hash: str, req: UpdateChunkRequest):
+    vault = get_vault_by_id(vault_id)
+    try:
+        if req.importance is not None:
+            vault.conn.execute("UPDATE chunks SET importance = ? WHERE content_hash = ?", (req.importance, content_hash))
+            vault.conn.commit()
+        return {"updated": True}
+    finally:
+        vault.close()