Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat: session tracking in MCP server with working set accumulation

riley02279145e55f9dff
diff --git a/ix-cli/src/mcp/__tests__/session.test.ts b/ix-cli/src/mcp/__tests__/session.test.ts
new file mode 100644
index 00000000..138dfc79
--- /dev/null
+++ b/ix-cli/src/mcp/__tests__/session.test.ts
@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { SessionState } from "../session.js";
+
+describe("SessionState", () => {
+ let session: SessionState;
+
+ beforeEach(() => {
+ session = new SessionState();
+ });
+
+ it("starts empty", () => {
+ const summary = session.getSummary();
+ expect(summary.totalActions).toBe(0);
+ expect(summary.queriedEntities).toEqual([]);
+ expect(summary.decisions).toEqual([]);
+ expect(summary.ingestedPaths).toEqual([]);
+ expect(summary.intents).toEqual([]);
+ expect(summary.recentActions).toEqual([]);
+ });
+
+ it("tracks queries", () => {
+ session.track({ type: "query", summary: "How does billing work?", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.totalActions).toBe(1);
+ expect(summary.recentActions).toHaveLength(1);
+ expect(summary.recentActions[0].type).toBe("query");
+ expect(summary.recentActions[0].summary).toBe("How does billing work?");
+ });
+
+ it("tracks entity IDs without duplicates", () => {
+ session.trackEntities(["id-1", "id-2", "id-1"]);
+ const summary = session.getSummary();
+ expect(summary.queriedEntities).toHaveLength(2);
+ expect(summary.queriedEntities).toContain("id-1");
+ expect(summary.queriedEntities).toContain("id-2");
+ });
+
+ it("tracks decisions", () => {
+ session.track({ type: "decision", id: "dec-1", summary: "Use REST over GraphQL", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.decisions).toContain("Use REST over GraphQL");
+ expect(summary.totalActions).toBe(1);
+ });
+
+ it("tracks ingested paths", () => {
+ session.track({ type: "ingest", summary: "src/main.ts", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.ingestedPaths).toContain("src/main.ts");
+ });
+
+ it("tracks intents from truth entries", () => {
+ session.track({ type: "truth", summary: "Build a fast API", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.intents).toContain("Build a fast API");
+ });
+
+ it("does not cross-populate categories", () => {
+ session.track({ type: "query", summary: "test query", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "entity", id: "e-1", summary: "Looked up entity e-1", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "conflict", summary: "Checked conflicts", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.decisions).toEqual([]);
+ expect(summary.ingestedPaths).toEqual([]);
+ expect(summary.intents).toEqual([]);
+ expect(summary.totalActions).toBe(3);
+ });
+
+ it("limits recent actions to 10", () => {
+ for (let i = 0; i < 15; i++) {
+ session.track({ type: "query", summary: `q${i}`, timestamp: "2025-01-01T00:00:00Z" });
+ }
+ const summary = session.getSummary();
+ expect(summary.totalActions).toBe(15);
+ expect(summary.recentActions).toHaveLength(10);
+ // Should be the most recent 10 (q5 through q14)
+ expect(summary.recentActions[0].summary).toBe("q5");
+ expect(summary.recentActions[9].summary).toBe("q14");
+ });
+
+ it("clears state", () => {
+ session.track({ type: "query", summary: "test", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "decision", id: "d-1", summary: "picked X", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "ingest", summary: "file.ts", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "truth", summary: "goal A", timestamp: "2025-01-01T00:00:00Z" });
+ session.trackEntities(["id-1"]);
+ session.clear();
+ const summary = session.getSummary();
+ expect(summary.totalActions).toBe(0);
+ expect(summary.queriedEntities).toEqual([]);
+ expect(summary.decisions).toEqual([]);
+ expect(summary.ingestedPaths).toEqual([]);
+ expect(summary.intents).toEqual([]);
+ expect(summary.recentActions).toEqual([]);
+ });
+
+ it("accumulates multiple entries of the same type", () => {
+ session.track({ type: "ingest", summary: "a.ts", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "ingest", summary: "b.ts", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "decision", id: "d-1", summary: "use X", timestamp: "2025-01-01T00:00:00Z" });
+ session.track({ type: "decision", id: "d-2", summary: "use Y", timestamp: "2025-01-01T00:00:00Z" });
+ const summary = session.getSummary();
+ expect(summary.ingestedPaths).toEqual(["a.ts", "b.ts"]);
+ expect(summary.decisions).toEqual(["use X", "use Y"]);
+ expect(summary.totalActions).toBe(4);
+ });
+
+ it("trackEntities accumulates across multiple calls", () => {
+ session.trackEntities(["id-1", "id-2"]);
+ session.trackEntities(["id-3", "id-1"]);
+ const summary = session.getSummary();
+ expect(summary.queriedEntities).toHaveLength(3);
+ expect(summary.queriedEntities).toContain("id-1");
+ expect(summary.queriedEntities).toContain("id-2");
+ expect(summary.queriedEntities).toContain("id-3");
+ });
+});
diff --git a/ix-cli/src/mcp/server.ts b/ix-cli/src/mcp/server.ts
index 596e39bc..5c6cec20 100644
--- a/ix-cli/src/mcp/server.ts
+++ b/ix-cli/src/mcp/server.ts
@@ -9,6 +9,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { IxClient } from "../client/api.js";
+import { SessionState } from "./session.js";
// ---------------------------------------------------------------------------
// Server instructions — sent to the LLM at connection time
@@ -36,6 +37,7 @@ BEHAVIORAL CHECKS:
// Client – uses IX_ENDPOINT env var or defaults to localhost:8090
// ---------------------------------------------------------------------------
const client = new IxClient(process.env.IX_ENDPOINT ?? "http://localhost:8090");
+const session = new SessionState();
// ---------------------------------------------------------------------------
// Server
@@ -59,6 +61,11 @@ server.tool(
async ({ question, asOfRev, depth }) => {
try {
const ctx = await client.query(question, { asOfRev, depth });
+ // Track session
+ session.track({ type: "query", summary: question, timestamp: new Date().toISOString() });
+ if (ctx.nodes) {
+ session.trackEntities(ctx.nodes.map((n: any) => n.id));
+ }
return {
content: [{ type: "text" as const, text: JSON.stringify(ctx, null, 2) }],
};
@@ -84,6 +91,8 @@ server.tool(
async ({ path, recursive }) => {
try {
const result = await client.ingest(path, recursive);
+ // Track session
+ session.track({ type: "ingest", summary: path, timestamp: new Date().toISOString() });
return {
content: [
{ type: "text" as const, text: JSON.stringify(result, null, 2) },
@@ -114,6 +123,8 @@ server.tool(
async ({ title, rationale, intentId }) => {
try {
const result = await client.decide(title, rationale, { intentId });
+ // Track session
+ session.track({ type: "decision", id: result.nodeId, summary: title, timestamp: new Date().toISOString() });
return {
content: [
{ type: "text" as const, text: JSON.stringify(result, null, 2) },
@@ -167,6 +178,9 @@ server.tool(
async ({ id }) => {
try {
const entity = await client.entity(id);
+ // Track session
+ session.track({ type: "entity", id, summary: `Looked up entity ${id}`, timestamp: new Date().toISOString() });
+ session.trackEntities([id]);
return {
content: [
{ type: "text" as const, text: JSON.stringify(entity, null, 2) },
@@ -248,6 +262,8 @@ server.tool(
async () => {
try {
const conflicts = await client.conflicts();
+ // Track session
+ session.track({ type: "conflict", summary: "Checked conflicts", timestamp: new Date().toISOString() });
return {
content: [
{ type: "text" as const, text: JSON.stringify(conflicts, null, 2) },
@@ -389,6 +405,8 @@ server.tool(
};
}
const result = await client.createTruth(statement, parentIntent);
+ // Track session
+ session.track({ type: "truth", summary: statement, timestamp: new Date().toISOString() });
return {
content: [
{ type: "text" as const, text: JSON.stringify(result, null, 2) },
@@ -449,20 +467,26 @@ server.tool(
server.resource(
"ix-session-context",
"ix://session/context",
- { description: "Session context nudge — review this at the start of each session" },
+ { description: "Session working set — entities queried, decisions made, files ingested in this session" },
async (uri) => {
- let text: string;
- try {
- const ctx = await client.query("session context overview", {});
- text = JSON.stringify(ctx, null, 2);
- } catch {
- text = [
- "Ix Memory session context is unavailable (server may not be running).",
- "Start the Ix Memory Layer server and try again.",
- ].join("\n");
+ const summary = session.getSummary();
+ let contextData: any = { session: summary };
+
+ // If there are queried entities, include a fresh context query
+ if (summary.queriedEntities.length > 0) {
+ try {
+ const ctx = await client.query(
+ `entities: ${summary.queriedEntities.slice(0, 5).join(", ")}`,
+ {},
+ );
+ contextData.latestContext = ctx;
+ } catch {
+ // Session data is still useful even without fresh query
+ }
}
+
return {
- contents: [{ uri: uri.href, mimeType: "application/json", text }],
+ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(contextData, null, 2) }],
};
},
);
diff --git a/ix-cli/src/mcp/session.ts b/ix-cli/src/mcp/session.ts
new file mode 100644
index 00000000..68095538
--- /dev/null
+++ b/ix-cli/src/mcp/session.ts
@@ -0,0 +1,78 @@
+/**
+ * Session State — in-memory working set tracking for the MCP server.
+ *
+ * Accumulates a record of tool invocations within a single session so that
+ * ix://session/context can return a rich summary of what the LLM has
+ * queried, decided, ingested, and recorded during the current session.
+ *
+ * Pure in-memory — the session resets when the MCP server process restarts.
+ */
+
+export interface SessionEntry {
+ type: "query" | "entity" | "decision" | "ingest" | "conflict" | "truth";
+ id?: string; // entity ID, decision ID, etc.
+ summary: string; // short description
+ timestamp: string; // ISO timestamp
+}
+
+export interface SessionSummary {
+ totalActions: number;
+ queriedEntities: string[]; // unique entity IDs
+ decisions: string[]; // decision titles
+ ingestedPaths: string[]; // file paths ingested
+ intents: string[]; // recorded intent statements
+ recentActions: SessionEntry[]; // last 10 entries
+}
+
+export class SessionState {
+ private entries: SessionEntry[] = [];
+ private queriedEntityIds: Set<string> = new Set();
+ private decidedTitles: string[] = [];
+ private ingestedPaths: string[] = [];
+ private recordedIntents: string[] = [];
+
+ /** Record a tool invocation */
+ track(entry: SessionEntry): void {
+ this.entries.push(entry);
+
+ switch (entry.type) {
+ case "decision":
+ this.decidedTitles.push(entry.summary);
+ break;
+ case "ingest":
+ this.ingestedPaths.push(entry.summary);
+ break;
+ case "truth":
+ this.recordedIntents.push(entry.summary);
+ break;
+ }
+ }
+
+ /** Record entity IDs seen in a query result */
+ trackEntities(ids: string[]): void {
+ for (const id of ids) {
+ this.queriedEntityIds.add(id);
+ }
+ }
+
+ /** Get the current working set summary (for ix://session/context) */
+ getSummary(): SessionSummary {
+ return {
+ totalActions: this.entries.length,
+ queriedEntities: [...this.queriedEntityIds],
+ decisions: [...this.decidedTitles],
+ ingestedPaths: [...this.ingestedPaths],
+ intents: [...this.recordedIntents],
+ recentActions: this.entries.slice(-10),
+ };
+ }
+
+ /** Clear session (for testing) */
+ clear(): void {
+ this.entries = [];
+ this.queriedEntityIds = new Set();
+ this.decidedTitles = [];
+ this.ingestedPaths = [];
+ this.recordedIntents = [];
+ }
+}