dsh-context-memory 0.1.0

package/lib/routes.js

@@ -0,0 +1,41 @@
+/**
+ * Host routes for the panel.
+ *
+ * Registered on the host's web connection when one exists. A host running headless
+ * simply skips registration and every other part of the plugin keeps working — the
+ * panel is a view of the log, not a precondition for keeping it.
+ *
+ * @module context-memory/routes
+ */
+/** The panel path, shared with the browser half so the two cannot drift apart. */
+export const MEMORY_PANEL_PATH = '/api/context-memory.panel';
+export function registerMemoryRoutes(ctx, memory) {
+    // Injecting rather than reading `ctx.connection` directly: a plain property access on
+    // a service that was not declared throws, and the web connection is absent in headless
+    // hosts anyway.
+    ctx.inject(['connection'], (connectionCtx) => {
+        const connection = connectionCtx.connection;
+        connection.fetch.register({
+            path: MEMORY_PANEL_PATH,
+            methods: ['GET'],
+            requestBody: 'buffered',
+            // Rebuilt from the log on every request: the panel must show the file's state,
+            // not whatever was in memory when the host started.
+            fetch: () => Promise.resolve(Response.json(memory.panel(), { headers: { 'cache-control': 'no-store' } })),
+        });
+        connection.fetch.register({
+            path: '/api/context-memory.verify',
+            methods: ['POST'],
+            requestBody: 'buffered',
+            fetch: async () => {
+                const summary = memory.verify();
+                return Response.json(summary, {
+                    // The verification is the answer, not an error: a violated memory is reported
+                    // with 200 and the caller decides what it means. Only a broken guard is a
+                    // defect in the request path itself, and that is reported in the payload.
+                    headers: { 'cache-control': 'no-store' },
+                });
+            },
+        });
+    });
+}

package/lib/store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The append-only event log.
+ *
+ * Memory has to survive the process that wrote it, and the interesting question later
+ * is never "what is the current value" but "why does the agent believe this". An
+ * append-only log answers both: current state is a fold, and the fold is reproducible
+ * from the file alone. A mutable store would let the last writer decide what was
+ * always true.
+ *
+ * @module context-memory/store
+ */
+import type { MemoryEvent } from './types.js';
+export declare class MemoryStore {
+    private readonly projectDir;
+    private readonly dir;
+    private readonly logPath;
+    constructor(projectDir: string);
+    get path(): string;
+    append(event: MemoryEvent): void;
+    /**
+     * Read the whole log.
+     *
+     * A process killed mid-write leaves one torn trailing line. That is a benign, expected
+     * shape after a crash, and refusing to read the entire history over it would trade a
+     * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
+     * anywhere else is a real problem and is reported rather than skipped, because
+     * silently ignoring a damaged record is how a log stops being evidence.
+     */
+    readAll(): MemoryEvent[];
+}

package/lib/store.js

@@ -0,0 +1,62 @@
+/**
+ * The append-only event log.
+ *
+ * Memory has to survive the process that wrote it, and the interesting question later
+ * is never "what is the current value" but "why does the agent believe this". An
+ * append-only log answers both: current state is a fold, and the fold is reproducible
+ * from the file alone. A mutable store would let the last writer decide what was
+ * always true.
+ *
+ * @module context-memory/store
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export class MemoryStore {
+    projectDir;
+    dir;
+    logPath;
+    constructor(projectDir) {
+        this.projectDir = projectDir;
+        this.dir = join(projectDir, '.memory');
+        this.logPath = join(this.dir, 'events.jsonl');
+    }
+    get path() {
+        return this.logPath;
+    }
+    append(event) {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        // One `write` of one line: a crash can truncate the final line, but cannot interleave.
+        appendFileSync(this.logPath, `${JSON.stringify(event)}\n`, 'utf8');
+    }
+    /**
+     * Read the whole log.
+     *
+     * A process killed mid-write leaves one torn trailing line. That is a benign, expected
+     * shape after a crash, and refusing to read the entire history over it would trade a
+     * recoverable loss for a total one — so a torn *final* line is dropped. Corruption
+     * anywhere else is a real problem and is reported rather than skipped, because
+     * silently ignoring a damaged record is how a log stops being evidence.
+     */
+    readAll() {
+        if (!existsSync(this.logPath))
+            return [];
+        const lines = readFileSync(this.logPath, 'utf8').split('\n');
+        const events = [];
+        for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index].trim();
+            if (line.length === 0)
+                continue;
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch (error) {
+                const isFinalLine = lines.slice(index + 1).every((rest) => rest.trim().length === 0);
+                if (isFinalLine)
+                    break;
+                throw new Error(`${this.logPath}: line ${index + 1} is not valid JSON: ${String(error)}`);
+            }
+        }
+        return events;
+    }
+}

package/lib/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Types for dsh-context-memory.
+ *
+ * The split between `Memory` (what was recorded) and `MemoryState` (what is currently
+ * true of it) mirrors the store: `Memory` is the immutable payload of a `remember`
+ * event, `MemoryState` is that payload folded together with every later event about it.
+ * Nothing in this plugin mutates a recorded memory — a memory stops being active
+ * because a later event says so, never because a field was overwritten.
+ *
+ * @module context-memory/types
+ */
+/** What kind of thing is being remembered. Affects presentation, not verification. */
+export type MemoryKind = 'fact' | 'decision' | 'preference' | 'pitfall';
+/** Who wrote the memory. Provenance, so "why does the agent think it knows this" has an answer. */
+export type MemorySource = 'user' | 'agent' | 'plugin';
+/** A memory is active until something explicitly supersedes it. */
+export type MemoryStatus = 'active' | 'superseded';
+/** The same three-outcome model dsh-verdict uses: inability to check is not failure. */
+export type GuardOutcome = 'passed' | 'violated' | 'broken';
+/** An executable check compiled from a memory statement. */
+export interface Guard {
+    command: string;
+    source: 'template';
+}
+/** The immutable payload recorded by a `remember` event. */
+export interface Memory {
+    id: string;
+    /** Normalised key a conflict is decided on; visible everywhere it is used. */
+    subject: string;
+    text: string;
+    kind: MemoryKind;
+    source: MemorySource;
+    createdAt: number;
+    sessionId?: string;
+    step?: number;
+    guard?: Guard;
+}
+/** A memory folded together with every later event about it. */
+export interface MemoryState extends Memory {
+    status: MemoryStatus;
+    supersededReason?: string;
+    supersededBy?: string;
+    verification?: {
+        at: number;
+        outcome: GuardOutcome;
+        exitCode: number | null;
+        output: string;
+    };
+}
+/**
+ * The append-only record. Every question the panel answers is derived by folding these,
+ * so "what happened" is never decided by whoever last held the file.
+ */
+export type MemoryEvent = {
+    type: 'remember';
+    at: number;
+    memory: Memory;
+} | {
+    type: 'supersede';
+    at: number;
+    id: string;
+    reason: string;
+    replacedBy?: string;
+} | {
+    type: 'verify';
+    at: number;
+    id: string;
+    outcome: GuardOutcome;
+    exitCode: number | null;
+    output: string;
+};
+/** One recall result, with the evidence for why it ranked where it did. */
+export interface RecallHit {
+    memory: MemoryState;
+    score: number;
+    /** Query tokens this memory actually contains. */
+    matched: string[];
+    /** Human-readable breakdown of the score, so a ranking is never unexplainable. */
+    why: string;
+}
+/** Two or more active memories sharing a subject but disagreeing about it. */
+export interface Conflict {
+    subject: string;
+    memories: MemoryState[];
+}
+/** One verification result per memory that was considered. */
+export interface VerifyResult {
+    id: string;
+    text: string;
+    /** `uncheckable` means no guard could be compiled — not that the memory is wrong. */
+    outcome: GuardOutcome | 'uncheckable';
+    exitCode: number | null;
+    output: string;
+}
+export interface VerifySummary {
+    passed: number;
+    violated: number;
+    broken: number;
+    uncheckable: number;
+    results: VerifyResult[];
+}
+/** Everything the panel needs, recomputed from the log on each read. */
+export interface PanelPayload {
+    active: MemoryState[];
+    superseded: MemoryState[];
+    conflicts: Conflict[];
+    totals: {
+        active: number;
+        superseded: number;
+        withGuard: number;
+        verified: number;
+        unverified: number;
+    };
+}

package/lib/types.js

@@ -0,0 +1,12 @@
+/**
+ * Types for dsh-context-memory.
+ *
+ * The split between `Memory` (what was recorded) and `MemoryState` (what is currently
+ * true of it) mirrors the store: `Memory` is the immutable payload of a `remember`
+ * event, `MemoryState` is that payload folded together with every later event about it.
+ * Nothing in this plugin mutates a recorded memory — a memory stops being active
+ * because a later event says so, never because a field was overwritten.
+ *
+ * @module context-memory/types
+ */
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "dsh-context-memory",
+  "version": "0.1.0",
+  "description": "Cross-session memory for your dsh agent: remembered, recalled, and re-verified instead of assumed.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": { "dsh-context-memory": "lib/bin.js" },
+  "exports": {
+    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
+    "./client": { "types": "./lib/client.d.ts", "default": "./lib/memory.web.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["lib", "cordis.patch.yml", "README.md", "CHANGELOG.md"],
+  "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "memory", "context", "recall", "persistence"],
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": ["@deepseek-ai/dsh-client-ui-settings", "@deepseek-ai/dsh-client-connection"]
+    }
+  },
+  "license": "MIT",
+  "author": "hj01857655",
+  "repository": { "type": "git", "url": "git+https://github.com/hj01857655/dsh-context-memory.git" },
+  "bugs": { "url": "https://github.com/hj01857655/dsh-context-memory/issues" },
+  "homepage": "https://github.com/hj01857655/dsh-context-memory#readme",
+  "engines": { "node": ">=20" },
+  "peerDependencies": { "@deepseek-ai/cordis": "^4.0.1" },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@types/node": "^22.20.3",
+    "@types/react": "^19.3.0",
+    "esbuild": "^0.28.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/bundle-client.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json",
+    "test": "tsc -p tsconfig.json && node --test",
+    "prepublishOnly": "npm run build && npm test"
+  }
+}