{
  "id": "page:docs-user-guide-ecosystem-kip-sdk",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/ecosystem/kip-sdk.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/ecosystem/kip-sdk.md",
    "sourceKind": "repo-docs",
    "title": "kip-sdk — memory substrate (built, private/unpublished)",
    "displayName": "kip-sdk — memory substrate (built, private/unpublished)",
    "slug": "docs/user-guide/ecosystem/kip-sdk",
    "articlePath": "wiki/docs/user-guide/ecosystem/kip-sdk.md",
    "article": "\n[Docs](../index.md) › [Ecosystem](./overview.md) › kip-sdk\n\n# kip-sdk — memory substrate (built, private/unpublished)\n\n**Package:** `@a5c-ai/kip-sdk` (`private: true`, `0.0.1` — unpublished) · **Path:** `packages/kip-sdk` · **Maturity:** Implemented / pre-release\n\n**kip is a signed, git-substrate, bitemporal, typed property-graph memory SDK — a durable memory layer for agents and applications where every fact is a signed, append-only record and every read is a deterministic projection over the fact set.** \"KIP\" stands for **K**(nowledge) / **I**(nference) / **P**(rovenance).\n\n> **This doc was previously wrong.** It used to say kip was \"spec/design only … no `package.json`, no `src/`, no shipping code, you cannot install or run it.\" That is **no longer true.** `packages/kip-sdk` now ships thousands of lines of TypeScript under `src/`, a real `package.json` with two `bin` entries, a working `open()`/`KipRepo` SDK, a `kip` CLI, a `kip-mcp` server, a graph-QA microagent behind `kip ask`, and a self-guarding conformance suite. It is **built and runnable today** — it is simply **not yet published to npm** (`private: true`, `0.0.1`). Use it from inside this monorepo (workspace import) or by building it and running the `dist/` output; there is no `npm install @a5c-ai/kip-sdk` yet.\n\n---\n\n## On this page\n\n- [Status: built, private, unpublished](#status-built-private-unpublished)\n- [What it is](#what-it-is)\n- [Surfaces you can run](#surfaces-you-can-run)\n- [Stack role](#stack-role)\n- [Honest limitations](#honest-limitations)\n- [Documentation](#documentation)\n- [Next steps](#next-steps)\n\n---\n\n## Status: built, private, unpublished\n\nkip is implemented, not a spec. The package declares a real build (`tsc` + a microagent-bundling step), a `vitest` test suite, and two binaries:\n\n```json\n// packages/kip-sdk/package.json (excerpt)\n\"private\": true,\n\"version\": \"0.0.1\",\n\"bin\": { \"kip\": \"dist/cli/kip.js\", \"kip-mcp\": \"dist/mcp/server.js\" }\n```\n\nBecause it is `private: true` at `0.0.1`, there is **no npm release**. You consume it in one of two ways — a workspace import inside this monorepo, or by building it and running the built `dist/` binaries directly. The only runtime dependency is [`isomorphic-git`](https://www.npmjs.com/package/isomorphic-git), so kip needs no system `git` binary. Full instructions are in the package [README](../../../packages/kip-sdk/README.md#install) and the [Getting started](../../../packages/kip-sdk/docs/guide/getting-started.md) guide.\n\n---\n\n## What it is\n\nMost agent \"memory\" is a pile of rows in a vector store: no history, no provenance, no way to know *who* wrote a fact or *when it was true*. kip is different:\n\n- **Every write is a signed fact.** A node, edge, or property value enters the store only as an append-only, Ed25519-signed fact. Set membership is decided by signature alone, so any two replicas that received the same facts compute the same graph — no coordinator, no locks (Strong Eventual Consistency).\n- **Reads are a pure projection.** The graph you read (`getNode`, `getEdge`, `query`, `recall`) is `proj(factSet)` — a deterministic, order-independent fold. A contradiction surfaces as a typed `conflict` cell rather than a silent last-writer-wins.\n- **Bitemporal by construction.** Facts carry both *valid time* (when the fact is true in the world) and *transaction time* (when the replica learned it), so you can ask \"what did we believe about X as of last Tuesday\" with `asOf(...)`.\n- **Forgetting is first-class.** `retract` bounds a fact's validity; `tombstone` marks an entity gone; `excise` physically erases bytes — all as further signed facts, never a destructive `UPDATE`.\n- **The substrate is git.** Facts are content-addressed git objects; sync is `git fetch` + a set-union merge. Memory is versioned, diffable, and replicable with tooling you already have.\n- **Retrieval + an active layer.** `recall` combines an exact/keyword graph seed with a caller-supplied embedding vector (exact-cosine); an active-knowledge layer compiles typed contextual queries and can run acquisition/learning microagents that author new signed facts under a single-author invariant.\n\nkip is a **library, not a runtime** (\"memory is a substrate, agents are clients\"). It ships two thin binaries over the same core so a human at a terminal and an MCP-speaking agent read and write the same signed graph.\n\n---\n\n## Surfaces you can run\n\n| Surface | What it is |\n|---------|-----------|\n| **SDK** (`open()` → `KipRepo`) | The exported barrel (`@a5c-ai/kip-sdk`) surfaces `open`, the `Repo` interface + view/type shapes, `KipError`, and the Ed25519 key helpers. `open()` creates/opens an on-disk repo; the returned `KipRepo` implements the full read/write/verify surface. See the [API reference](../../../packages/kip-sdk/docs/guide/api.md). |\n| **`kip` CLI** | `dist/cli/kip.js`. Commands include `init`, `assert` (forms: `node` / `edge` / `fact`, with `--prop` to set properties), `get`, `query`, `recall`, `asof`, `sync`, `fsck`, `rollup`, and `ask`. See the [CLI reference](../../../packages/kip-sdk/docs/guide/cli.md). |\n| **`kip-mcp` server** | `dist/mcp/server.js`, a stdio MCP server exposing **ten** tools: `kip_assert`, `kip_retract`, `kip_get_node`, `kip_get_edge`, `kip_query`, `kip_recall`, `kip_asof`, `kip_sync`, `kip_fsck`, and `kip_ask`. See the [MCP guide](../../../packages/kip-sdk/docs/guide/mcp.md). |\n| **Graph-QA (`kip ask` / `kip_ask`)** | A read-only graph-QA microagent that answers natural-language questions over the graph. It retrieves facts, then synthesizes prose by spawning your already-authenticated local `claude` CLI. On dispatch failure it exits non-zero rather than fabricating an answer. |\n| **Conformance suite** | A self-guarding, shippable invariant suite: **40** `INV-*` invariants (`INV-1..INV-19` plus milestone sub-invariants and the active-knowledge set `INV-A1..INV-A14`), each with a per-invariant test, plus a completeness guard that fails CI if an invariant goes missing. See the [conformance guide](../../../packages/kip-sdk/docs/maintainer/conformance-guide.md). |\n\nThe 60-second SDK flow (every call is part of the real public surface):\n\n```js\nimport { open } from \"@a5c-ai/kip-sdk\";\n\n// Open a memory repo, creating it if the directory is empty.\nconst repo = await open({\n  dir: \"./my-memory\",\n  replicaId: \"laptop-1\",   // stable author id for this replica (required)\n  keyring: {},             // an empty keyring mints a fresh Ed25519 signing key\n  createIfMissing: true,\n});\n\nawait repo.putNode({ eid: \"ada\", kind: \"Person\", props: { name: \"Ada Lovelace\", born: 1815 } });\nawait repo.putNode({ eid: \"babbage\", kind: \"Person\", props: { name: \"Charles Babbage\" } });\nawait repo.putEdge({ kind: \"knows\", from: \"ada\", to: \"babbage\", validFrom: \"2020-01-01\" });\n\nconst ada = await repo.getNode(\"ada\");\nconsole.log(ada.kind, \"=>\", ada.props.name.segments[0].value); // Person => Ada Lovelace\n\nconst report = await repo.fsck(); // heads match proj(facts), all signatures verify\nconsole.log(\"healthy:\", report.ok);\n```\n\n---\n\n## Stack role\n\nkip is designed as the **memory substrate** for the ecosystem: babysitter-sdk, genty, the adapters family, atlas, and kradle are all potential producers/consumers/clients of its seams. The substrate and its SDK/CLI/MCP surfaces are built today; the *cross-package wiring* into the rest of the ecosystem is not yet delivered — treat kip's integration points as designed-and-available-to-consume, not as shipped end-to-end integrations. This is why the [ecosystem overview](./overview.md) and [architecture](../architecture.md) place kip alongside the runtime as an implemented-but-unwired memory layer rather than a GA product.\n\n---\n\n## Honest limitations\n\nkip is early. Where a reader could be misled, the docs say so plainly (the package tracks these in [`DEBTS.md`](../../../packages/kip-sdk/docs/DEBTS.md)):\n\n- **Not published.** `private: true`, `0.0.1`. Use it via the workspace or the built `dist/` — not `npm install`.\n- **`recall` is an exact cosine scan, not ANN.** The vector half is a brute-force per-call cosine scan (recall-equal to exact kNN); there is no HNSW/IVF index or embedding cache yet. Embeddings are **caller-supplied** — kip never embeds text for you. The `text` field is an exact/keyword graph seed, not a semantic search.\n- **`kip ask` needs a host model and costs money.** Graph-QA synthesis spawns your already-authenticated local `claude` CLI; there is no bundled model. Without one it **fails loudly** (dispatch-failure exit code) rather than fabricating, and a live ask costs roughly **$0.02–0.045**.\n- **Some `Repo` methods are still stubs.** Notably `commit()` throws `unimplemented` (use `txn()` for a commit boundary); `sync()` is pull-only (no push); and cross-replica / transaction-time selectors (`asOf`/`pin` with a foreign-replica `txTime`/`believer` lens) throw `unimplemented` rather than guessing. The [API reference](../../../packages/kip-sdk/docs/guide/api.md) marks each method ✅ / ⚠️ / 🚧.\n\n---\n\n## Documentation\n\n**Consumer-facing** (start here to use kip):\n\n- [Package README](../../../packages/kip-sdk/README.md) — the pitch, install, and quickstart.\n- [Getting started](../../../packages/kip-sdk/docs/guide/getting-started.md) — a hands-on SDK walkthrough (open/init, assert, read, query, recall, `asOf`, `fsck`).\n- [CLI reference](../../../packages/kip-sdk/docs/guide/cli.md) — every `kip` command, its flags, stdout shapes, and exit codes.\n- [MCP server](../../../packages/kip-sdk/docs/guide/mcp.md) — launching `kip-mcp`, registering it, and its ten tools.\n- [API reference](../../../packages/kip-sdk/docs/guide/api.md) — the exported `open()` / `Repo` surface and an honest implemented-vs-stub map.\n\n**Maintainer-facing** (changing kip's code):\n\n- [Architecture](../../../packages/kip-sdk/docs/maintainer/architecture.md) — the real current module layout and load-bearing invariants.\n- [Conformance guide](../../../packages/kip-sdk/docs/maintainer/conformance-guide.md) — how the self-guarding invariant suite works and how to add an `INV-*` test.\n- [Contributing](../../../packages/kip-sdk/docs/maintainer/contributing.md) — house rules, the `DEBTS.md` convention, and the TDD/adversarial-review workflow.\n\nThe pre-development design record — `SPEC.md` and the numbered `docs/00..90` design docs — lives under [`packages/kip-sdk/docs/`](../../../packages/kip-sdk/docs/README.md); it is now the internal design history behind the shipped code, not a substitute for it.\n\n---\n\n## Next steps\n\n- **Use it:** [Package README](../../../packages/kip-sdk/README.md) → [Getting started](../../../packages/kip-sdk/docs/guide/getting-started.md)\n- **See where it sits:** [Architecture & How It Fits Together](../architecture.md)\n- **Ecosystem map:** [Ecosystem Overview](./overview.md)\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide",
      "to": "page:docs-user-guide-ecosystem-kip-sdk",
      "kind": "contains_page"
    }
  ]
}