@100xprompt/chitta 0.1.0

package/src/install/platforms.ts

@@ -0,0 +1,126 @@
+// The platform registry: one row per AI tool, with its EXACT (verified 2025-2026) MCP
+// config location + format and Skill directory. Paths are resolved per-OS at call time.
+// Adding a tool = adding a row here; the writers in writers.ts handle each `format`.
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const HOME = homedir()
+const PLAT = process.platform // "darwin" | "linux" | "win32"
+
+// App-data root per OS (where Electron/VS Code apps store user config).
+const appData = (): string =>
+  PLAT === "darwin" ? join(HOME, "Library", "Application Support")
+  : PLAT === "win32" ? (process.env.APPDATA ?? join(HOME, "AppData", "Roaming"))
+  : join(HOME, ".config")
+
+// VS Code "User" dir (settings.json / mcp.json / globalStorage live here).
+const vscodeUser = (): string => join(appData(), "Code", "User")
+
+/** How the MCP server entry is shaped + where it nests. */
+export type Format =
+  | "json"   // JSON object: container[key][name] = entry
+  | "json-array" // JSON: container[key] is an ARRAY of entries (Trae)
+  | "toml"   // Codex TOML
+  | "manual" // no stable on-disk path → print instructions
+
+/** The per-tool server-entry dialect. */
+export type Entry = "standard" | "vscode" | "zed" | "local" | "trae"
+
+export interface Platform {
+  id: string
+  label: string
+  format: Format
+  /** top-level container key in the config (e.g. mcpServers / servers / context_servers / mcp / amp.mcpServers) */
+  key?: string
+  entry?: Entry
+  /** absolute global/user config path (null if tool has no global file) */
+  global: string | null
+  /** project-relative config path (undefined if not supported) */
+  project?: string
+  /** skill dirs (we append `/chitta/SKILL.md`); undefined if tool has no skills */
+  skillGlobal?: string
+  skillProject?: string
+  /** optional note shown to the user */
+  note?: string
+}
+
+export const PLATFORMS: Platform[] = [
+  {
+    id: "claude-code", label: "Claude Code", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".claude.json"), project: ".mcp.json",
+    skillGlobal: join(HOME, ".claude", "skills"), skillProject: ".claude/skills",
+    note: "global edits ~/.claude.json; `claude mcp add` is the official alternative.",
+  },
+  {
+    id: "claude-desktop", label: "Claude Desktop", format: "json", key: "mcpServers", entry: "standard",
+    global: join(appData(), "Claude", "claude_desktop_config.json"),
+    note: "restart Claude Desktop after install (config is read once at startup).",
+  },
+  {
+    id: "cursor", label: "Cursor", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".cursor", "mcp.json"), project: ".cursor/mcp.json",
+    skillGlobal: join(HOME, ".cursor", "skills"), skillProject: ".cursor/skills",
+  },
+  {
+    id: "vscode", label: "VS Code (Copilot)", format: "json", key: "servers", entry: "vscode",
+    global: join(vscodeUser(), "mcp.json"), project: ".vscode/mcp.json",
+  },
+  {
+    id: "windsurf", label: "Windsurf", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+  },
+  {
+    id: "zed", label: "Zed", format: "json", key: "context_servers", entry: "zed",
+    global: join(HOME, ".config", "zed", "settings.json"), project: ".zed/settings.json",
+  },
+  {
+    id: "cline", label: "Cline", format: "json", key: "mcpServers", entry: "standard",
+    global: join(vscodeUser(), "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+  },
+  {
+    id: "roo", label: "Roo Code", format: "json", key: "mcpServers", entry: "standard",
+    global: join(vscodeUser(), "globalStorage", "rooveterinaryinc.roo-cline", "settings", "mcp_settings.json"),
+    project: ".roo/mcp.json",
+  },
+  {
+    id: "codex", label: "Codex CLI", format: "toml",
+    global: join(HOME, ".codex", "config.toml"), project: ".codex/config.toml",
+  },
+  {
+    id: "gemini", label: "Gemini CLI", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".gemini", "settings.json"), project: ".gemini/settings.json",
+    skillGlobal: join(HOME, ".gemini", "skills"), skillProject: ".gemini/skills",
+  },
+  {
+    id: "opencode", label: "opencode", format: "json", key: "mcp", entry: "local",
+    global: join(HOME, ".config", "opencode", "opencode.json"), project: "opencode.json",
+    skillGlobal: join(HOME, ".config", "opencode", "skills"), skillProject: ".opencode/skills",
+  },
+  {
+    id: "kiro", label: "Kiro", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".kiro", "settings", "mcp.json"), project: ".kiro/settings/mcp.json",
+    skillGlobal: join(HOME, ".kiro", "skills"), skillProject: ".kiro/skills",
+  },
+  {
+    id: "amp", label: "Amp", format: "json", key: "amp.mcpServers", entry: "standard",
+    global: join(appData(), "amp", "settings.json"), project: ".amp/settings.json",
+    skillGlobal: join(HOME, ".config", "agents", "skills"), skillProject: ".agents/skills",
+  },
+  {
+    id: "factory", label: "Factory Droid", format: "json", key: "mcpServers", entry: "standard",
+    global: join(HOME, ".factory", "mcp.json"), project: ".factory/mcp.json",
+    skillGlobal: join(HOME, ".factory", "skills"), skillProject: ".factory/skills",
+  },
+  {
+    id: "kilo", label: "Kilo Code", format: "json", key: "mcp", entry: "local",
+    global: join(HOME, ".config", "kilo", "kilo.json"), project: ".kilo/kilo.json",
+    skillGlobal: join(HOME, ".kilo", "skills"), skillProject: ".kilo/skills",
+  },
+  {
+    id: "trae", label: "Trae", format: "json-array", key: "mcpServers", entry: "trae",
+    global: null, skillProject: ".trae/skills",
+    note: "Trae's global MCP file path is undocumented; add via the in-app MCP panel (use --print), Skill installs to .trae/skills.",
+  },
+]
+
+export const byId = (id: string): Platform | undefined => PLATFORMS.find((p) => p.id === id)

package/src/install/skill.ts

@@ -0,0 +1,46 @@
+// Skill installer — copies the bundled SKILL.md into a tool's skills directory as
+// <skillsDir>/chitta/SKILL.md. Tools that support Claude-style skills get guidance on
+// WHEN to use Chitta's MCP tools (recall before answering, ingest durable facts, etc.).
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+// assets/skill/SKILL.md lives at repo root (../../assets from src/install). When compiled,
+// the build embeds it next to the binary; fall back to an inline copy if not found.
+const SKILL_SRC_CANDIDATES = [
+  join(HERE, "..", "..", "assets", "skill", "SKILL.md"),
+  join(HERE, "assets", "skill", "SKILL.md"),
+]
+
+const INLINE_FALLBACK = `---
+name: chitta
+description: Permission-aware long-term memory for AI agents. Use to recall prior context before answering, store durable facts/decisions, and query how concepts relate. Backed by Chitta's MCP tools (context_ingest, get_context, context_graph).
+---
+
+# Chitta — memory for this agent
+
+Chitta gives you persistent, permission-aware memory via MCP tools. Use it proactively.
+
+- **Before answering** anything that may depend on prior work, call **get_context** with the
+  user's question to retrieve ranked, cited, permission-filtered snippets.
+- **After learning** a durable fact, decision, or preference, call **context_ingest** to store it.
+- To understand **how things relate**, call **context_graph**.
+
+If MCP tools are unavailable, use the CLI: \`bunx @100xprompt/chitta query "<q>"\` and
+\`bunx @100xprompt/chitta ingest --text "<fact>"\`.
+`
+
+export function skillContent(): string {
+  for (const p of SKILL_SRC_CANDIDATES) if (existsSync(p)) return readFileSync(p, "utf8")
+  return INLINE_FALLBACK
+}
+
+/** Write chitta/SKILL.md under the given skills directory. Returns the file path. */
+export function installSkill(skillsDir: string): string {
+  const dir = join(skillsDir, "chitta")
+  mkdirSync(dir, { recursive: true })
+  const dst = join(dir, "SKILL.md")
+  writeFileSync(dst, skillContent())
+  return dst
+}

package/src/install/writers.ts

@@ -0,0 +1,82 @@
+// Config writers — one per FORMAT, not per tool. Each MERGES into existing config so other
+// MCP servers and unrelated settings are preserved, and re-running is idempotent.
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs"
+import { dirname } from "node:path"
+import type { Entry } from "./platforms"
+
+export const PKG = "@100xprompt/chitta"
+// Chitta runs on the Bun runtime, so it launches via `bunx` (Bun's package runner).
+// Users need Bun once: `curl -fsSL https://bun.sh/install | bash`.
+const RUN = ["bunx", PKG] // [command, ...args]
+
+/** Build the server-entry object in the dialect a given tool expects. */
+export function serverEntry(entry: Entry, env: Record<string, string>): unknown {
+  const hasEnv = Object.keys(env).length > 0
+  const cmd = { command: "bunx", args: [PKG] }
+  switch (entry) {
+    case "standard":
+      return { ...cmd, ...(hasEnv ? { env } : {}) }
+    case "vscode":
+      return { type: "stdio", ...cmd, ...(hasEnv ? { env } : {}) }
+    case "zed":
+      return { source: "custom", ...cmd, ...(hasEnv ? { env } : {}) }
+    case "local": // opencode / kilo: combined command array + `environment` + enabled
+      return { type: "local", command: [...RUN], enabled: true, ...(hasEnv ? { environment: env } : {}) }
+    case "trae": // array entry carrying its own name + combined command array
+      return { name: "chitta", command: [...RUN], ...(hasEnv ? { env } : {}) }
+  }
+}
+
+function readJson(path: string): any {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, "utf8").trim()
+  if (!raw) return {}
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // tolerate JSONC line comments (VS Code / opencode allow them)
+    return JSON.parse(raw.replace(/^\s*\/\/.*$/gm, ""))
+  }
+}
+
+/** Merge `chitta` into a JSON config under `key`. Object form (most tools) or array form (Trae). */
+export function writeJsonConfig(
+  path: string,
+  key: string,
+  entry: unknown,
+  array: boolean,
+): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const cfg = readJson(path)
+  if (array) {
+    const list = Array.isArray(cfg[key]) ? cfg[key] : []
+    const filtered = list.filter((e: any) => e?.name !== "chitta")
+    filtered.push(entry)
+    cfg[key] = filtered
+  } else {
+    if (typeof cfg[key] !== "object" || cfg[key] === null || Array.isArray(cfg[key])) cfg[key] = {}
+    cfg[key]["chitta"] = entry
+  }
+  writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n")
+}
+
+/** Codex TOML: replace-or-append the [mcp_servers.chitta] block (+ optional env table). */
+export function writeCodexToml(path: string, env: Record<string, string>): void {
+  mkdirSync(dirname(path), { recursive: true })
+  let text = existsSync(path) ? readFileSync(path, "utf8") : ""
+  // strip any existing chitta block (the table + its sub-tables up to the next top-level [table])
+  text = text.replace(/\n*\[mcp_servers\.chitta\][\s\S]*?(?=\n\[[^.\]]|\n\[mcp_servers\.(?!chitta)|\s*$)/g, "\n")
+  text = text.replace(/\n{3,}/g, "\n\n").trimEnd()
+  let block = `\n\n[mcp_servers.chitta]\ncommand = "bunx"\nargs = ["${PKG}"]\n`
+  const keys = Object.keys(env)
+  if (keys.length) {
+    block += `\n[mcp_servers.chitta.env]\n`
+    for (const k of keys) block += `${k} = ${JSON.stringify(env[k])}\n`
+  }
+  writeFileSync(path, (text + block).trimStart() + "\n")
+}
+
+/** The generic snippet for --print / unsupported clients. */
+export function printSnippet(env: Record<string, string>): string {
+  return JSON.stringify({ mcpServers: { chitta: serverEntry("standard", env) } }, null, 2)
+}

package/src/mcp/backend.ts

@@ -0,0 +1,129 @@
+// Resolves which backend the MCP server talks to, from env:
+//   • Central office: if CONTEXT_ARANGO_URL/QDRANT_URL/EMBED_URL/COLLECTION are set,
+//     query the shared backend with this user's identity → org-wide graph + per-user ACL.
+//   • Local embedded (default): a single SQLite file - ingest + query, no servers.
+// Identity (who is asking) drives ACL and comes from CONTEXT_USER_ID/CONTEXT_ORG_ID.
+
+import { personalContext, personalContextPath } from "../embedded/personal"
+import { buildContextService } from "../service"
+import { loadContextConfigFromEnv } from "../config-env"
+import type { IngestDoc } from "../embedded/ingest"
+import type { RetrievalResponse } from "../types"
+
+export interface KnowledgeGraph {
+  entities: Array<{ id: string; label: string; type: string }>
+  relations: Array<{ from: string; to: string }>
+}
+
+export interface BackendStats {
+  records: number
+  chunks: number
+  entities: number
+  relations: number
+}
+
+export interface ExactAnswer {
+  answer: string
+  facts: string[]
+  triple: { subject: string; predicate: string; object: string }
+  citations: string[]
+  confidence: number
+}
+
+export interface ContextBackend {
+  mode: "central" | "local"
+  userId: string
+  orgId: string
+  /** Where the data lives (db path for local, backend url for central). */
+  storage: string
+  /** Active vector search engine. */
+  vectorIndex: string
+  /** Configured embedding mode (auto/transformers/hash, or central). */
+  embeddings: string
+  /** Knowledge extraction mode - confirms whether the LLM is wired. */
+  extraction: string
+  query(q: string): Promise<RetrievalResponse>
+  /** KGQA: exact answer from the typed graph, or null to fall back to ranked. */
+  ask?: (q: string) => Promise<ExactAnswer | null>
+  ingest?: (doc: IngestDoc) => Promise<{ recordId: string; chunks: number; entities: number }>
+  /** The accessible knowledge graph (entities + relations). Local mode only. */
+  graph?: () => Promise<KnowledgeGraph>
+  /** Re-extract the knowledge graph over all records with the current extractor
+   *  (typed triples when an LLM is configured). Local mode only. */
+  rebuild?: () => Promise<{ records: number; entities: number }>
+  /** Graph-query surface (ACL-filtered traversal over the entity graph). Local only. */
+  graphQuery?: {
+    neighbors: (name: string, relation?: string) => Promise<unknown>
+    path: (a: string, b: string) => Promise<unknown>
+    impact: (name: string) => Promise<unknown>
+    central: (limit?: number) => Promise<unknown>
+    communities: () => Promise<unknown>
+    cypher: () => Promise<string>
+    walk: (seeds: string[]) => Promise<unknown>
+  }
+  /** Live counts for the about/discovery endpoint. */
+  stats?: () => Promise<BackendStats>
+}
+
+export function resolveBackend(): ContextBackend {
+  const central = loadContextConfigFromEnv(process.env)
+
+  if (central) {
+    const userId = process.env.CONTEXT_USER_ID
+    const orgId = process.env.CONTEXT_ORG_ID
+    if (!userId || !orgId) {
+      throw new Error("central mode needs CONTEXT_USER_ID and CONTEXT_ORG_ID so results are ACL-filtered")
+    }
+    const svc = buildContextService(central)
+    return {
+      mode: "central",
+      userId,
+      orgId,
+      storage: central.qdrant.url,
+      vectorIndex: "Qdrant (hybrid + RRF)",
+      embeddings: "central embedding service",
+      extraction: "central ingestion pipeline",
+      // Ingestion in the central tier is normally via connectors - not exposed here.
+      query: (q) => svc.retrieval.searchWithFilters({ queries: [q], userId, orgId, limit: 10 }),
+    }
+  }
+
+  const ctx = personalContext()
+  const count = (sql: string) => (ctx.store.db.query(sql).get() as { c: number }).c
+  return {
+    mode: "local",
+    userId: ctx.userId,
+    orgId: ctx.orgId,
+    storage: personalContextPath(),
+    vectorIndex: ctx.store.vecEnabled ? "sqlite-vec ANN (in-process)" : "brute-force cosine",
+    embeddings: (process.env.CONTEXT_EMBEDDINGS ?? "auto").toLowerCase(),
+    extraction: process.env.CONTEXT_LLM_URL
+      ? `LLM typed-triples (${process.env.CONTEXT_LLM_MODEL || "default"} @ ${process.env.CONTEXT_LLM_URL})`
+      : "caller-supplied typed triples (the calling model passes entities+relations to context_ingest); " +
+        "deterministic fallback when none given",
+    query: (q) => ctx.searchWithGraph(q, ctx.userId, ctx.orgId), // vector + ACL + GraphRAG expansion
+    ask: (q) => ctx.ask(q, ctx.userId, ctx.orgId), // KGQA: exact answer from the typed graph
+    ingest: (doc) => ctx.authorizedIngest(ctx.userId, doc), // write-side authorization + ownership
+    graph: async () => {
+      const accessible = await ctx.graph.getAccessibleVirtualRecordIds({ userId: ctx.userId, orgId: ctx.orgId })
+      const recordIds = [...new Set(Object.values(accessible))]
+      return ctx.graph.getKnowledgeGraph(recordIds)
+    },
+    rebuild: () => ctx.rebuildGraph(),
+    graphQuery: {
+      neighbors: (name, relation) => ctx.graphQuery.neighbors(name, ctx.userId, ctx.orgId, relation),
+      path: (a, b) => ctx.graphQuery.pathBetween(a, b, ctx.userId, ctx.orgId),
+      impact: (name) => ctx.graphQuery.impactOf(name, ctx.userId, ctx.orgId),
+      central: (limit) => ctx.graphQuery.central(ctx.userId, ctx.orgId, limit),
+      communities: () => ctx.graphQuery.communities(ctx.userId, ctx.orgId),
+      cypher: () => ctx.graphQuery.toCypher(ctx.userId, ctx.orgId),
+      walk: (seeds) => ctx.graphQuery.walk(seeds, ctx.userId, ctx.orgId),
+    },
+    stats: async () => ({
+      records: count("SELECT count(*) c FROM nodes WHERE coll = 'records'"),
+      chunks: count("SELECT count(*) c FROM chunks"),
+      entities: count("SELECT count(*) c FROM nodes WHERE coll = 'entities'"),
+      relations: count("SELECT count(*) c FROM edges WHERE label = 'relates_to'"),
+    }),
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+// 100x Context - MCP server. Exposes the knowledge graph as standard MCP tools so
+// ANY client (100xprompt, Claude Desktop, Cursor, IDEs) uses it via config alone,
+// no code changes. Ships as one command; point it at the central office backend
+// with env (see backend.ts) to share one org-wide graph with per-user ACL.
+//
+//   Client config:
+//   "mcp": { "context": { "type": "local", "command": ["chitta"],
+//            "environment": { "CONTEXT_USER_ID": "alice", "CONTEXT_ORG_ID": "acme" } } }
+//
+// The 6 tools live one-per-module under ./tools; this file just wires the server:
+// resolve the backend, build the (capability-gated) tool list, register ListTools
+// from those schemas, dispatch CallTool through the name→handler map, and connect
+// the stdio transport.
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+import { resolveBackend } from "./backend"
+import { resolveTools } from "./tools"
+
+const backend = resolveBackend()
+const { schemas, dispatch } = resolveTools(backend)
+
+const INSTRUCTIONS = [
+  "100x Context - a permission-aware knowledge graph + vector memory. It is the user's / organization's",
+  "long-term memory. Treat it as the source of truth for anything personal or organization-specific.",
+  "",
+  "WHEN TO USE EACH TOOL:",
+  "• context_ingest - Call WHENEVER the user states something durable worth remembering: facts, preferences,",
+  "  people, projects, decisions, documents, or any 'remember that…/store…/note that…/I am/like/work on…'.",
+  "  Don't ask permission for obvious saves - just store it. Not for transient chit-chat.",
+  "  YOU ARE THE EXTRACTOR: you just read and understood this content, so ALWAYS pass the `entities` and",
+  "  `relations` you identified alongside the text. Relations are subject→predicate→object with a SHORT",
+  "  snake_case predicate (partners_with, acquired, works_at, deploys, located_in, ceo_of…). This stores precise",
+  "  TYPED triples - no second model re-reads the text, and the graph can answer relational questions exactly.",
+  "• get_context - Call BEFORE answering ANY question that could touch the user's own notes, people, projects,",
+  "  org knowledge, or prior statements ('who/what/when did I…', 'what do we know about…', 'remind me…').",
+  "  Always check memory first instead of guessing. If it returns nothing, say so plainly.",
+  "• context_graph - Call when the user asks how things relate, for an overview, or 'what do you know about X' /",
+  "  'how are these connected' - it returns the concept map (entities + relationships).",
+  "• context_about - Call to discover this server's capabilities, current mode, storage, engines, and live stats",
+  "  (e.g. when unsure what memory can do, or to report status).",
+  "",
+  "HOW IT WORKS (set expectations from this):",
+  "• Two stores behind one interface: a GRAPH (records, people, concepts + relationships + permissions) and a",
+  "  VECTOR store (semantic search). get_context combines them: ACL-filter (what the user may see) → semantic",
+  "  search over only those records → expand along the concept graph → return ranked, cited snippets.",
+  "• EVERYTHING IS PERMISSION-FILTERED. Results only ever contain what the asking user is authorized to see.",
+  "  Never assume the user can access more than what comes back; never invent beyond the returned content.",
+  "• WRITES ARE AUTHORIZED TOO: roles (admin/editor/viewer) gate creation; only an owner or admin may delete/",
+  "  modify a record; non-admins can't share outside their org/groups. If a write is denied, relay that plainly.",
+  "",
+  "TIER SYSTEM (set by config, not by you - tool behavior is identical either way):",
+  "• local (default): a single private SQLite store on this machine - personal memory, no servers.",
+  "• central-office: a shared organization-wide store (ArangoDB graph + Qdrant vectors). Everyone shares one",
+  "  knowledge base, but each user sees only what their ACL permits. Identity comes from CONTEXT_USER_ID/ORG_ID.",
+  "",
+  "DEFAULT BEHAVIOR: prefer recall over guessing (get_context first); ingest durable facts proactively; cite",
+  "what you retrieve.",
+].join("\n")
+
+const server = new Server(
+  { name: "100x-context", version: "0.1.0" },
+  { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: schemas }))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params
+  try {
+    const handler = dispatch.get(name)
+    if (!handler) return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true }
+    return await handler(args as Record<string, unknown>, backend)
+  } catch (e) {
+    const msg = e instanceof Error && e.name === "AuthorizationError" ? `Not authorized: ${e.message}` : `error: ${String(e)}`
+    return { content: [{ type: "text", text: msg }], isError: true }
+  }
+})
+
+await server.connect(new StdioServerTransport())
+console.error(`[100x-context] MCP server ready (mode=${backend.mode}, user=${backend.userId})`)

package/src/mcp/tools/context-about.ts

@@ -0,0 +1,69 @@
+import { CodeExtractor } from "../../embedded/code-extractor"
+import type { ContextBackend } from "../backend"
+import type { ToolModule, ToolResult, ToolSchema } from "./types"
+
+// The about/describe output lists every AVAILABLE tool with its description. The
+// index injects the resolved tool list (after capability gating) so this stays in
+// lockstep with what ListTools reports - identical to the old inline TOOLS loop.
+let listedTools: ToolSchema[] = []
+export function setAboutToolList(tools: ToolSchema[]): void {
+  listedTools = tools
+}
+
+const schema = {
+  name: "context_about",
+  description:
+    "Describe this context server: its purpose, current mode/identity/storage, the vector + knowledge-graph " +
+    "engines in use, live counts, and every tool with what it's for. Call this first to discover capabilities.",
+  inputSchema: { type: "object" as const, properties: {} },
+}
+
+// Self-describing capability report for discovery (the context_about tool).
+async function describe(backend: ContextBackend): Promise<string> {
+  const lines: string[] = [
+    "# 100x Context - permission-aware knowledge graph + vector memory (MCP server)",
+    "",
+    "Stores PROSE or CODE as: a record node + permission edges (ACL) + vector chunks + an extracted graph.",
+    "Code files are parsed with tree-sitter into a real code graph (functions/classes + calls/imports/defines),",
+    "so the same graph queries (neighbors / path / impact / communities) work over code as well as notes.",
+    "Retrieval = ACL filter (who can see what) → semantic vector search (restricted to accessible records) →",
+    "GraphRAG expansion along concept links → ranked, cited snippets.",
+    "",
+    "The graph is BI-TEMPORAL and self-densifying: every relationship carries a weight that accumulates as it's",
+    "re-asserted (frequency≈confidence), provenance (which records asserted it), and validity intervals. New facts",
+    "MERGE into existing ones rather than duplicating; a newer single-valued fact (e.g. moved cities) SUPERSEDES the",
+    "old one non-destructively - the prior fact stays in history (marked expired) and never surfaces as current.",
+    "",
+    "## Current state",
+    `- mode: ${backend.mode}  ·  user: ${backend.userId}  ·  org: ${backend.orgId}`,
+    `- storage: ${backend.storage}`,
+    `- vector search: ${backend.vectorIndex}`,
+    `- embeddings: ${backend.embeddings}`,
+    `- knowledge extraction: ${backend.extraction}`,
+    `- code graph: tree-sitter AST over ${CodeExtractor.languages().length} languages (functions/classes + calls/imports/defines)`,
+  ]
+  if (backend.stats) {
+    const s = await backend.stats()
+    lines.push(`- contents: ${s.records} record(s), ${s.chunks} chunk(s), ${s.entities} concept(s), ${s.relations} relationship(s)`)
+  }
+  lines.push("", "## Tools")
+  for (const t of listedTools) lines.push(`- **${t.name}** - ${t.description}`)
+  lines.push(
+    "",
+    "## Modes",
+    "- personal (default): one private SQLite file, single owner - no ACL friction.",
+    "- TEAM / multi-user (embedded): point multiple clients at the SAME SQLite file (CONTEXT_DB) but give each",
+    "  its own CONTEXT_USER_ID / CONTEXT_ORG_ID / CONTEXT_USER_ROLE / CONTEXT_USER_GROUPS. ONE shared graph",
+    "  (entities are a common backbone), but every user sees ONLY their ACL slice - private to the owner, shared",
+    "  with named groups (context_ingest `share`), or org-wide (`org_wide`). Edges are permission-filtered per",
+    "  provenance, so a private relationship between two otherwise-visible entities never leaks.",
+    "- central-office: set CONTEXT_ARANGO_URL/QDRANT_URL/EMBED_URL/COLLECTION → server-backed org graph, same ACL.",
+  )
+  return lines.join("\n")
+}
+
+async function handler(_args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  return { content: [{ type: "text", text: await describe(backend) }] }
+}
+
+export const contextAboutTool: ToolModule = { schema, handler }

package/src/mcp/tools/context-graph.ts

@@ -0,0 +1,23 @@
+import type { ContextBackend } from "../backend"
+import type { ToolModule, ToolResult } from "./types"
+
+const schema = {
+  name: "context_graph",
+  description:
+    "See how stored concepts connect. USE WHEN: the user asks for an overview, 'what do you know about X', " +
+    "'how are these related', or wants the map of their knowledge. Returns entities + relationships " +
+    "(permission-filtered). DON'T USE to fetch document text - that's get_context.",
+  inputSchema: { type: "object" as const, properties: {} },
+}
+
+async function handler(_args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  const g = await backend.graph!()
+  const byId = new Map(g.entities.map((e) => [e.id, e.label]))
+  const lines = [
+    `Knowledge graph: ${g.entities.length} concept(s), ${g.relations.length} relationship(s).`,
+    ...g.relations.slice(0, 50).map((r) => `  ${byId.get(r.from) ?? r.from} ── ${byId.get(r.to) ?? r.to}`),
+  ]
+  return { content: [{ type: "text", text: lines.join("\n") }] }
+}
+
+export const contextGraphTool: ToolModule = { schema, handler, available: (b) => !!b.graph }

package/src/mcp/tools/context-ingest.ts

@@ -0,0 +1,88 @@
+import type { ContextBackend } from "../backend"
+import { slug, type ToolModule, type ToolResult } from "./types"
+
+const schema = {
+  name: "context_ingest",
+  description:
+    "Remember new information durably. USE WHEN: the user states a fact, preference, person, project, " +
+    "decision, or document worth keeping, or says 'remember/store/note that…'. Don't ask permission for " +
+    "obvious saves - just store it. Writes a record + permission edges (ACL) + vector chunks + a concept " +
+    "graph. IMPORTANT: YOU already understood this content, so ALSO pass the `entities` and `relations` you " +
+    "extracted - they're stored as precise TYPED triples (no second model re-reads it). Relations should be " +
+    "subject→predicate→object with a SHORT snake_case predicate (e.g. partners_with, acquired, works_at, " +
+    "deploys, located_in). DON'T USE for transient chit-chat or one-off computations.",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      content: { type: "string", description: "text to store" },
+      name: { type: "string", description: "short title" },
+      entities: {
+        type: "array",
+        description: "entities you identified in the content (people, orgs, products, concepts)",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "entity name as written" },
+            type: { type: "string", description: "PERSON | ORG | PRODUCT | CONCEPT | PLACE | …" },
+          },
+          required: ["name"],
+        },
+      },
+      relations: {
+        type: "array",
+        description: "typed relationships between entities (subject → predicate → object)",
+        items: {
+          type: "object",
+          properties: {
+            from: { type: "string", description: "subject entity name" },
+            to: { type: "string", description: "object entity name" },
+            type: { type: "string", description: "SHORT snake_case predicate, e.g. partners_with / acquired / works_at" },
+            confidence: { type: "number", description: "0..1 how certain (optional)" },
+          },
+          required: ["from", "to", "type"],
+        },
+      },
+      share: {
+        type: "array",
+        description: "principal ids (users or groups) to ALSO grant read access - default is private to you",
+        items: { type: "string" },
+      },
+      org_wide: { type: "boolean", description: "share with everyone in your org (default false)" },
+    },
+    required: ["content", "name"],
+  },
+}
+
+async function handler(args: Record<string, unknown>, backend: ContextBackend): Promise<ToolResult> {
+  const a = args as {
+    content: string
+    name: string
+    entities?: Array<{ name: string; type?: string }>
+    relations?: Array<{ from: string; to: string; type: string; confidence?: number }>
+    share?: string[]
+    org_wide?: boolean
+  }
+  // owner is always added by authorizedIngest; `share` widens to named principals/
+  // groups; `org_wide` shares with everyone in the org. The authorizer rejects any
+  // grant outside the caller's scope (no over-sharing).
+  const principals = [...new Set([backend.userId, ...(a.share ?? [])])]
+  const out = await backend.ingest!({
+    recordId: `${slug(a.name)}-${Date.now().toString(36)}`,
+    orgId: backend.orgId,
+    recordName: a.name,
+    text: a.content,
+    permittedPrincipals: principals,
+    shareWithOrg: a.org_wide ? backend.orgId : undefined,
+    entities: a.entities,
+    relations: a.relations,
+  })
+  const typed = a.relations?.length ? `, ${a.relations.length} typed relation(s)` : ""
+  const vis = a.org_wide ? "org-wide" : a.share?.length ? `shared with ${a.share.join(", ")}` : "private"
+  return {
+    content: [
+      { type: "text", text: `Stored "${a.name}" (${out.chunks} chunk(s), ${out.entities} concept(s)${typed}; ${vis}) as ${out.recordId}.` },
+    ],
+  }
+}
+
+export const contextIngestTool: ToolModule = { schema, handler, available: (b) => !!b.ingest }