mcp-kb-sqlite 0.1.0__py3-none-any.whl

mcp_kb_sqlite/db/__init__.py

@@ -0,0 +1,38 @@
+import os
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+
+from mcp_kb_sqlite.db.migrations import run_migrations
+
+_db_path: Path | None = None
+
+
+def get_db_path() -> Path:
+    global _db_path
+    if _db_path is None:
+        raw = os.environ.get("DB_PATH")
+        if raw:
+            _db_path = Path(raw)
+        else:
+            _db_path = Path.home() / ".ai-memory" / "kb.db"
+        os.makedirs(_db_path.parent, exist_ok=True)
+    return _db_path
+
+
+@contextmanager
+def get_conn():
+    conn = sqlite3.connect(get_db_path(), timeout=30)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.execute("PRAGMA foreign_keys = ON")
+    try:
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def init_db() -> None:
+    with get_conn() as conn:
+        run_migrations(conn)

mcp_kb_sqlite/db/migrations.py

@@ -0,0 +1,76 @@
+def _migrate_v0(conn) -> None:
+    """Baseline schema — single entries table with FTS on title/description/tags."""
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS db_meta (
+            key   TEXT PRIMARY KEY,
+            value TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS entries (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            ns          TEXT NOT NULL,
+            key         TEXT NOT NULL,
+            title       TEXT NOT NULL,
+            description TEXT,
+            tags        TEXT,
+            data        TEXT,
+            created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+            updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+            UNIQUE(ns, key)
+        );
+
+        CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts
+            USING fts5(title, description, tags, content='entries', content_rowid='id');
+
+        CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+            INSERT INTO entries_fts(rowid, title, description, tags)
+            VALUES (new.id, new.title, new.description, new.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, title, description, tags)
+            VALUES ('delete', old.id, old.title, old.description, old.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+            INSERT INTO entries_fts(entries_fts, rowid, title, description, tags)
+            VALUES ('delete', old.id, old.title, old.description, old.tags);
+            INSERT INTO entries_fts(rowid, title, description, tags)
+            VALUES (new.id, new.title, new.description, new.tags);
+            UPDATE entries SET updated_at = CURRENT_TIMESTAMP WHERE id = new.id;
+        END;
+
+        CREATE TABLE IF NOT EXISTS relations (
+            from_id  INTEGER NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+            to_id    INTEGER NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+            rel      TEXT NOT NULL,
+            PRIMARY KEY (from_id, to_id, rel)
+        );
+    """)
+
+
+MIGRATIONS = [_migrate_v0]
+
+
+def _get_schema_version(conn) -> int:
+    import sqlite3
+    try:
+        row = conn.execute("SELECT value FROM db_meta WHERE key='schema_version'").fetchone()
+        return int(row["value"]) if row else 0
+    except sqlite3.OperationalError:
+        return 0
+
+
+def _set_schema_version(conn, version: int) -> None:
+    conn.execute(
+        "INSERT OR REPLACE INTO db_meta(key, value) VALUES ('schema_version', ?)",
+        (str(version),),
+    )
+
+
+def run_migrations(conn) -> None:
+    version = _get_schema_version(conn)
+    for i, fn in enumerate(MIGRATIONS, start=1):
+        if i > version:
+            fn(conn)
+            _set_schema_version(conn, i)

mcp_kb_sqlite/db/queries.py

@@ -0,0 +1,220 @@
+import json
+import sqlite3
+
+from mcp_kb_sqlite.db import get_conn
+
+
+class EntryNotFound(Exception):
+    def __init__(self, id: int):
+        self.id = id
+        super().__init__(f"id={id}")
+
+
+class EntryClash(Exception):
+    def __init__(self, ns: str, key: str, id: int):
+        self.ns = ns
+        self.key = key
+        self.id = id
+        super().__init__(f"{ns}/{key} already exists (id={id})")
+
+
+def _ns_params(ns: str) -> list:
+    return [ns, ns + "/%"]
+
+
+def _ns_filter_sql(ns: str | None) -> tuple[str, list]:
+    """SQL condition (without leading AND/WHERE) plus its params for an ns-prefix filter.
+    Empty string/params when ns is None — callers splice it into their own WHERE clause."""
+    if not ns:
+        return "", []
+    return "(e.ns = ? OR e.ns LIKE ?)", _ns_params(ns)
+
+
+def _clash(conn, ns: str, key: str):
+    return conn.execute(
+        "SELECT id FROM entries WHERE ns = ? AND key = ?", (ns, key)
+    ).fetchone()
+
+
+def create_entry(ns, key, title, description, tags, data) -> dict:
+    """Insert a new entry. Raises ValueError if ns/key/title missing, EntryClash if the
+    (ns, key) pair is taken. Returns {'id', 'ns', 'key'}."""
+    if not ns or not key or not title:
+        raise ValueError("create requires ns, key, and title (or pass id to update)")
+    with get_conn() as conn:
+        clash = _clash(conn, ns, key)
+        if clash:
+            raise EntryClash(ns, key, clash["id"])
+        cur = conn.execute(
+            """
+            INSERT INTO entries(ns, key, title, description, tags, data)
+            VALUES (?, ?, ?, ?, ?, ?)
+            RETURNING id
+            """,
+            (ns, key, title, description, json.dumps(tags) if tags else None, data),
+        )
+        id_ = cur.fetchone()["id"]
+    return {"id": id_, "ns": ns, "key": key}
+
+
+def _update_sets(ns, key, title, description, tags, data) -> tuple[list[str], list]:
+    """Column assignments for the fields that were actually passed.
+
+    A field left as None is omitted entirely; "" (or [] for tags) clears it.
+    Column names come from these literals only — never from caller input.
+    """
+    sets: list[str] = []
+    params: list = []
+    for col, provided, val in (
+        ("ns", ns is not None, ns),
+        ("key", key is not None, key),
+        ("title", title is not None, title),
+        ("description", description is not None, description or None),
+        ("tags", tags is not None, json.dumps(tags) if tags else None),
+        ("data", data is not None, data or None),
+    ):
+        if provided:
+            sets.append(f"{col} = ?")
+            params.append(val)
+    return sets, params
+
+
+def update_entry(id, ns, key, title, description, tags, data) -> dict:
+    """Patch-update an entry. Raises ValueError for invalid input, EntryNotFound if id
+    doesn't exist, EntryClash if renaming (ns, key) collides with another entry.
+    Returns {'id', 'ns', 'key', 'changed': [col, ...]}."""
+    if "" in (ns, key, title):
+        raise ValueError("ns, key, and title cannot be cleared")
+    sets, params = _update_sets(ns, key, title, description, tags, data)
+    if not sets:
+        raise ValueError("nothing to update — pass at least one field alongside id")
+    with get_conn() as conn:
+        row = conn.execute(
+            "SELECT id, ns, key FROM entries WHERE id = ?", (id,)
+        ).fetchone()
+        if not row:
+            raise EntryNotFound(id)
+        new_ns = ns if ns is not None else row["ns"]
+        new_key = key if key is not None else row["key"]
+        if (new_ns, new_key) != (row["ns"], row["key"]):
+            clash = _clash(conn, new_ns, new_key)
+            if clash:
+                raise EntryClash(new_ns, new_key, clash["id"])
+        # SET clause interpolates only the literal column names from _update_sets(); every
+        # caller-supplied value is bound as a parameter. updated_at is set by the
+        # entries_au trigger, not here.
+        sql = f"UPDATE entries SET {', '.join(sets)} WHERE id = ?"
+        conn.execute(sql, [*params, id])
+    changed = [s.split(" = ")[0] for s in sets]
+    return {"id": id, "ns": new_ns, "key": new_key, "changed": changed}
+
+
+def get_entry(id: int) -> sqlite3.Row | None:
+    with get_conn() as conn:
+        return conn.execute(
+            "SELECT id, ns, key, title, description, tags, data, created_at, updated_at "
+            "FROM entries WHERE id = ?",
+            (id,),
+        ).fetchone()
+
+
+def search_entries(query: str, ns: str | None, limit: int, offset: int) -> list[sqlite3.Row]:
+    ns_sql, ns_params = _ns_filter_sql(ns)
+    with get_conn() as conn:
+        # ns_sql is a fixed literal from _ns_filter_sql(), never caller input; the ns
+        # value itself is bound as a parameter via ns_params.
+        return conn.execute(
+            f"""
+            SELECT e.id, e.ns, e.key, e.title, e.updated_at,
+                   snippet(entries_fts, 1, '**', '**', '...', 20) AS snip
+            FROM entries_fts
+            JOIN entries e ON e.id = entries_fts.rowid
+            WHERE entries_fts MATCH ?
+              {"AND " + ns_sql if ns_sql else ""}
+            ORDER BY bm25(entries_fts) ASC
+            LIMIT ? OFFSET ?
+            """,
+            [query, *ns_params, limit, offset],
+        ).fetchall()
+
+
+def list_entries(ns: str | None, limit: int, offset: int) -> tuple[list[sqlite3.Row], int]:
+    ns_sql, ns_params = _ns_filter_sql(ns)
+    where = f"WHERE {ns_sql}" if ns_sql else ""
+    with get_conn() as conn:
+        total = conn.execute(
+            f"SELECT COUNT(*) FROM entries e {where}", ns_params
+        ).fetchone()[0]
+        rows = conn.execute(
+            f"""
+            SELECT e.id, e.ns, e.key, e.title, e.updated_at
+            FROM entries e
+            {where}
+            ORDER BY e.updated_at DESC
+            LIMIT ? OFFSET ?
+            """,
+            [*ns_params, limit, offset],
+        ).fetchall()
+    return rows, total
+
+
+def list_namespaces() -> list[sqlite3.Row]:
+    with get_conn() as conn:
+        return conn.execute(
+            """
+            SELECT ns, COUNT(*) AS cnt, MAX(updated_at) AS last_updated
+            FROM entries
+            GROUP BY ns
+            ORDER BY ns
+            """
+        ).fetchall()
+
+
+def add_relation(from_id: int, to_id: int, rel: str) -> None:
+    """Raises EntryNotFound (with the first missing id) if either endpoint doesn't exist."""
+    with get_conn() as conn:
+        ids = {
+            r["id"]
+            for r in conn.execute(
+                "SELECT id FROM entries WHERE id IN (?, ?)", (from_id, to_id)
+            ).fetchall()
+        }
+        missing = {from_id, to_id} - ids
+        if missing:
+            raise EntryNotFound(min(missing))
+        conn.execute(
+            "INSERT OR IGNORE INTO relations(from_id, to_id, rel) VALUES (?, ?, ?)",
+            (from_id, to_id, rel),
+        )
+
+
+def remove_relation(from_id: int, to_id: int) -> int:
+    """Returns the number of relation rows removed (both directions)."""
+    with get_conn() as conn:
+        cur = conn.execute(
+            "DELETE FROM relations WHERE (from_id=? AND to_id=?) OR (from_id=? AND to_id=?)",
+            (from_id, to_id, to_id, from_id),
+        )
+        return cur.rowcount
+
+
+def get_relations(id: int) -> list[sqlite3.Row]:
+    with get_conn() as conn:
+        return conn.execute(
+            """
+            SELECT r.rel, r.from_id, r.to_id,
+                   e.ns, e.key, e.title, e.updated_at,
+                   CASE WHEN r.from_id = ? THEN 'outgoing' ELSE 'incoming' END AS direction
+            FROM relations r
+            JOIN entries e ON e.id = CASE WHEN r.from_id = ? THEN r.to_id ELSE r.from_id END
+            WHERE r.from_id = ? OR r.to_id = ?
+            ORDER BY r.rel, e.ns, e.key
+            """,
+            (id, id, id, id),
+        ).fetchall()
+
+
+def delete_entry(id: int) -> bool:
+    with get_conn() as conn:
+        cur = conn.execute("DELETE FROM entries WHERE id = ?", (id,))
+        return bool(cur.rowcount)

mcp_kb_sqlite/server.py

@@ -0,0 +1,197 @@
+import json
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.utilities.func_metadata import ArgModelBase
+from pydantic import ConfigDict
+
+from mcp_kb_sqlite.db import init_db, queries
+
+# Tool argument models otherwise silently drop unknown fields (pydantic's default
+# extra="ignore"), so a misnamed param (e.g. "payload" instead of "data") looks
+# like a successful call instead of erroring. Forbid extras for every @mcp.tool()
+# defined below — must run before those decorators execute.
+ArgModelBase.model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+mcp = MCPServer("mcp-kb-sqlite", instructions="Project knowledge base — search here before querying external sources; store cross-service architecture facts, investigation findings, and patterns worth preserving across sessions. Tools: search, save, get, list, relate, delete.")
+
+
+def _fmt_date(ts: str | None) -> str:
+    return ts[:10] if ts else "?"
+
+
+@mcp.tool()
+def save(
+    id: int | None = None,
+    ns: str | None = None,
+    key: str | None = None,
+    title: str | None = None,
+    description: str | None = None,
+    tags: list[str] | None = None,
+    data: str | None = None,
+) -> str:
+    """Create or update a KB entry. Two modes:
+    UPDATE — pass id plus only the fields you want to change. Omitted fields keep their current
+    value; pass "" (or [] for tags) to clear description/tags/data. ns/key/title can be changed
+    but not cleared. Errors if no entry has that id.
+    CREATE — omit id and pass ns, key, and title (all three required). Errors if ns+key is taken;
+    the error reports the existing id so you can re-issue it as an update.
+    ns = namespace like 'project/subsystem', key = unique slug within ns.
+    title: short label (FTS-indexed). description: search-hint field — write the keywords/synonyms
+    a user would actually query here, not just a prose summary (FTS-indexed).
+    tags: 3-5 keywords (FTS-indexed). data: large payload, NOT FTS-indexed — anything you want
+    findable must appear in title, description, or tags instead. Retrieved via get()."""
+    try:
+        if id is None:
+            result = queries.create_entry(ns, key, title, description, tags, data)
+            return f"Created: {result['ns']}/{result['key']} (id={result['id']})"
+        result = queries.update_entry(id, ns, key, title, description, tags, data)
+        changed = ", ".join(result["changed"])
+        return f"Updated: {result['ns']}/{result['key']} (id={result['id']}) — fields: {changed}"
+    except ValueError as e:
+        return f"Error: {e}"
+    except queries.EntryNotFound as e:
+        return f"Not found: id={e.id}"
+    except queries.EntryClash as e:
+        return f"Error: {e.ns}/{e.key} already exists (id={e.id}) — pass id={e.id} to update it"
+
+
+@mcp.tool()
+def get(id: int, include_data: bool = False) -> str:
+    """Fetch a KB entry by id. Returns title, description, tags, and dates by default.
+    Pass include_data=True to also retrieve the data payload."""
+    row = queries.get_entry(id)
+    if not row:
+        return f"Not found: id={id}"
+    tags = json.loads(row["tags"]) if row["tags"] else []
+    tags_str = f"  tags={tags}" if tags else ""
+    desc_str = f"\n{row['description']}" if row["description"] else ""
+    header = (
+        f"id={row['id']} | {row['ns']}/{row['key']}{tags_str}"
+        f"  created: {_fmt_date(row['created_at'])}  updated: {_fmt_date(row['updated_at'])}\n"
+        f"{row['title']}{desc_str}"
+    )
+    if include_data and row["data"]:
+        return f"{header}\n\n{row['data']}"
+    return header
+
+
+@mcp.tool()
+def search(
+    query: str,
+    ns: str | None = None,
+    limit: int = 10,
+    offset: int = 0,
+) -> str:
+    """Full-text search over entries using FTS5/BM25. Searches title, description, and tags.
+    Optionally filter by ns prefix. FTS5 operators AND, OR, NOT work as-is. Wrap query in double quotes for strict phrase search — special characters (dots, hyphens, etc.) become literals inside quotes, e.g. "127.0.0.1"."""
+    limit = min(limit, 100)
+    rows = queries.search_entries(query, ns, limit, offset)
+
+    if not rows:
+        return "No results."
+
+    lines = []
+    for r in rows:
+        lines.append(f"id={r['id']} | {r['ns']}/{r['key']}  updated: {_fmt_date(r['updated_at'])}")
+        lines.append(f"  {r['title']}")
+        if r["snip"]:
+            lines.append(f"  {r['snip']}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def list(
+    ns: str | None = None,
+    limit: int = 20,
+    offset: int = 0,
+) -> str:
+    """List entries (id, ns/key, title, updated_at). Optionally filter by ns prefix."""
+    limit = min(limit, 100)
+    rows, total = queries.list_entries(ns, limit, offset)
+
+    if not rows:
+        return "No entries found."
+
+    lines = [
+        f"id={r['id']} | {r['ns']}/{r['key']} | {r['title']} | {_fmt_date(r['updated_at'])}"
+        for r in rows
+    ]
+    shown_end = offset + len(rows)
+    if total > shown_end:
+        lines.append(f"({shown_end} of {total} — use offset={shown_end} for more)")
+    else:
+        lines.append(f"({total} total)")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def list_namespaces() -> str:
+    """List all namespaces with entry counts and last-updated date.
+    Use this first to discover available projects/topics before calling search or list."""
+    rows = queries.list_namespaces()
+
+    if not rows:
+        return "No namespaces found."
+
+    lines = []
+    prev_top = None
+    for r in rows:
+        top = r["ns"].split("/")[0]
+        if top != prev_top:
+            if prev_top is not None:
+                lines.append("")
+            prev_top = top
+        lines.append(f"{r['ns']} ({r['cnt']}) {_fmt_date(r['last_updated'])}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def relate(from_id: int, to_id: int, rel: str | None = "see_also") -> str:
+    """Create or remove a typed relation between two entries.
+    rel given or omitted (default: see_also) → add relation (INSERT OR IGNORE). Not validated —
+    pick freely, but prefer these for consistency: see_also, part_of, caused_by, example_of.
+    rel explicitly null → delete all relations between the pair (both directions)."""
+    if rel is not None:
+        try:
+            queries.add_relation(from_id, to_id, rel)
+        except queries.EntryNotFound as e:
+            return f"Not found: id={e.id}"
+        return f"Related {from_id} --[{rel}]--> {to_id}"
+    removed = queries.remove_relation(from_id, to_id)
+    return f"Unrelated {from_id} <--> {to_id} ({removed} removed)"
+
+
+@mcp.tool()
+def get_relations(id: int) -> str:
+    """Get all entries related to a given entry id (both directions)."""
+    rows = queries.get_relations(id)
+
+    if not rows:
+        return f"No relations found for id={id}"
+
+    lines = [f"Relations for id={id}:"]
+    for r in rows:
+        arrow = "-->" if r["direction"] == "outgoing" else "<--"
+        other_id = r["to_id"] if r["direction"] == "outgoing" else r["from_id"]
+        lines.append(
+            f"  [{r['rel']}] {arrow} id={other_id} | {r['ns']}/{r['key']} — {r['title']}"
+            f"  (updated: {_fmt_date(r['updated_at'])})"
+        )
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def delete(id: int) -> str:
+    """Delete a KB entry by id."""
+    if queries.delete_entry(id):
+        return f"Deleted id={id}"
+    return f"Not found: id={id}"
+
+
+def main() -> None:
+    init_db()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_kb_sqlite-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: mcp-kb-sqlite
+Version: 0.1.0
+Summary: Local long-term memory MCP server backed by SQLite FTS5
+Project-URL: Homepage, https://github.com/eukos/mcp-kb-sqlite
+Author-email: Eugene Kosyakov <eukos@yandex.by>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,fts5,knowledge-base,llm,mcp,memory,opencode,sqlite
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<3,>=2
+Requires-Dist: pydantic>=2
+Description-Content-Type: text/markdown
+
+# mcp-kb-sqlite
+
+Simple, fast persistent memory for your coding agent — cross-session, cross-project. One knowledge
+base shared across every repo you work in, so what you learn in one project is there the next time
+you open another. Entries can be linked to each other (`relate`), so related facts stay connected
+instead of scattered.
+
+Start a conversation with `/kb-use` to load relevant context before you begin. When you learn
+something worth keeping — an architecture decision, a gotcha, a debugging finding — save it with
+`/kb-update`.
+
+Under the hood: a plain SQLite database with an FTS5 full-text index, and a small tool surface for
+agents to search, save, and link entries. No server to run, no external service, no schema to
+manage by hand.
+
+## Install — MCP server
+
+The database lives at `~/.ai-memory/kb.db` unless you override it with `DB_PATH` (shown below,
+optional). The schema is created and migrated automatically on first connection.
+
+### Claude Code
+
+```sh
+claude mcp add kb -- uv run --directory /path/to/mcp-kb-sqlite mcp-kb-sqlite
+
+# with a custom DB_PATH:
+claude mcp add kb --env DB_PATH=/path/to/kb.db -- uv run --directory /path/to/mcp-kb-sqlite mcp-kb-sqlite
+```
+
+Or add it directly to `.mcp.json` (project-local) or `~/.claude.json` (user-scoped, under the
+top-level `mcpServers` key):
+
+```json
+{
+  "mcpServers": {
+    "kb": {
+      "type": "stdio",
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/mcp-kb-sqlite", "mcp-kb-sqlite"],
+      "env": { "DB_PATH": "/path/to/kb.db" }
+    }
+  }
+}
+```
+
+`env` is optional — drop it to use the default `~/.ai-memory/kb.db`.
+
+### OpenCode
+
+Add to `opencode.json` (global at `~/.config/opencode/opencode.json`, or project-local):
+
+```json
+{
+  "mcp": {
+    "kb": {
+      "type": "local",
+      "command": [
+        "uv",
+        "run",
+        "--directory",
+        "/path/to/mcp-kb-sqlite",
+        "mcp-kb-sqlite"
+      ],
+      "enabled": true,
+      "environment": { "DB_PATH": "/path/to/kb.db" }
+    }
+  }
+}
+```
+
+`environment` is optional — drop it to use the default `~/.ai-memory/kb.db`.
+
+## Install — skills
+
+The `/kb-use` and `/kb-update` workflows ship as skills for both Claude Code and OpenCode. The two
+flavors are hand-kept in sync — there's no generator, so edit both when instructions change.
+
+### Claude Code
+
+Copy or symlink `skills/claude/commands/*.md` into `~/.claude/commands/`.
+
+### OpenCode
+
+Copy or symlink each `skills/opencode/<name>/` directory into `~/.config/opencode/skills/<name>/`
+(or a project-local `.opencode/skills/`). OpenCode skills are auto-invoked by description match via
+the agent's `skill` tool, but can also be triggered directly as `/<name>` in chat — this prepends
+the SKILL.md text and appends whatever you typed after the command.
+
+## Tools
+
+| Tool                                                       | Purpose                                                       |
+| ---------------------------------------------------------- | ------------------------------------------------------------- |
+| `save(id?, ns?, key?, title?, description?, tags?, data?)` | Create or update an entry — see below                         |
+| `get(id, include_data=False)`                              | Fetch one entry; `include_data=True` returns the payload      |
+| `search(query, ns?, limit=10, offset=0)`                   | FTS5/BM25 over title + description + tags                     |
+| `list(ns?, limit=20, offset=0)`                            | Entries by recency, metadata only                             |
+| `list_namespaces()`                                        | Namespaces with entry counts and last-updated date            |
+| `relate(from_id, to_id, rel?)`                             | Link two entries; omit `rel` to remove all links between them |
+| `get_relations(id)`                                        | Links in both directions                                      |
+| `delete(id)`                                               | Remove an entry (cascades to its relations)                   |
+
+Entries are addressed by `ns` (namespace, e.g. `project/subsystem`) plus `key` (a slug unique within the
+namespace). `ns` filters are prefix matches, so `ns="project"` covers every subsystem under it.
+
+Only `title`, `description`, and `tags` are FTS-indexed. `data` is the payload — put schemas, code, configs
+and traces there, and make sure anything you need to _find_ also appears in one of the indexed fields.
+
+### `save`: create vs. update
+
+Every parameter is optional; the presence of `id` picks the mode.
+
+**Update** — pass `id` plus only the fields you want to change:
+
+```python
+save(id=42, description="new search hints")   # title, tags, data untouched
+```
+
+Omitted fields keep their current value. Pass `""` (or `[]` for `tags`) to clear `description`, `tags`, or
+`data`. `ns`, `key`, and `title` can be changed — that's how you rename or move an entry — but not cleared.
+
+**Create** — omit `id`; `ns`, `key`, and `title` are all required:
+
+```python
+save(ns="project/db", key="schema", title="Schema layout", tags=["db","schema"], data="…")
+```
+
+There is no upsert. Creating over an existing `(ns, key)` is an error that reports the existing id, so an
+accidental full overwrite isn't possible:
+
+```
+Error: project/db/schema already exists (id=42) — pass id=42 to update it
+```

mcp_kb_sqlite-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mcp_kb_sqlite/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_kb_sqlite/server.py,sha256=U14GROUj-HegsGpdX0NIOBQFQ7eHlPjubvnNg3-Xhz4,7465
+mcp_kb_sqlite/db/__init__.py,sha256=dyIoPv00gvuZ8MFDwj3L9ozl1-ZMW37Ydy0NnX9Ii9A,864
+mcp_kb_sqlite/db/migrations.py,sha256=c-TnF3s3IPR-D-ix0WjjF9eMEYTNtdOFf7eZZcoL9Vk,2832
+mcp_kb_sqlite/db/queries.py,sha256=Xjcjn50IpLQ21g18GGz7DoLuwXmn312vFKg49zAu_Pc,7967
+mcp_kb_sqlite-0.1.0.dist-info/METADATA,sha256=98tlG-GVdp_DI2iBZsXFx_WI5NfkQ_3uesXfKcgy6oA,5875
+mcp_kb_sqlite-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcp_kb_sqlite-0.1.0.dist-info/entry_points.txt,sha256=kXw3Qh3KT2MAHyxhrHK-NqNJ0jUlHupqacrtOv97WvM,60
+mcp_kb_sqlite-0.1.0.dist-info/licenses/LICENSE,sha256=tdNgBtlRWF1KbLtPlYVZuomItZsT1Xrbab__zrlJpbY,1072
+mcp_kb_sqlite-0.1.0.dist-info/RECORD,,

mcp_kb_sqlite-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_kb_sqlite-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-kb-sqlite = mcp_kb_sqlite.server:main

mcp_kb_sqlite-0.1.0.dist-info/licenses/LICENSE

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