agent-memory-store 0.0.1

package/README.MD

@@ -0,0 +1,290 @@
+# agent-memory-store
+
+> Local-first MCP memory server for multi-agent systems.
+
+[![npm version](https://img.shields.io/npm/v/agent-memory-store.svg)](https://www.npmjs.com/package/agent-memory-store)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)
+
+`agent-memory-store` gives your AI agents a shared, searchable, persistent memory — running entirely on your local filesystem. No vector database, no embedding APIs, no cloud services required.
+
+Agents read and write **chunks** (markdown files with YAML frontmatter) through a set of MCP tools. Search is powered by **BM25**, the same ranking algorithm used by Elasticsearch, implemented in pure JavaScript with zero runtime dependencies.
+
+```
+                 ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+                 │   Agent A   │   │   Agent B   │   │   Agent C   │
+                 └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
+                        │                 │                  │
+                        └────────────────┬─────────────────-┘
+                                         │  MCP tools
+                              ┌──────────▼──────────┐
+                              │     agent-memory-store      │
+                              │  search · write      │
+                              │  read · state · list │
+                              └──────────┬──────────┘
+                                         │
+                              ┌──────────▼──────────┐
+                              │  .agent-memory-store/       │
+                              │  ├── chunks/         │
+                              │  └── state/          │
+                              └─────────────────────-┘
+```
+
+## Features
+
+- **Zero-install usage** via `npx`
+- **BM25 full-text search** — relevance ranking without embeddings or APIs
+- **Tag and agent filtering** — find chunks by who wrote them or what they cover
+- **TTL-based expiry** — chunks auto-delete after a configurable number of days
+- **Session state** — key/value store for pipeline progress, flags, and counters
+- **Plain files** — chunks are `.md` files, readable and editable by humans and git
+- **MCP-native** — works with Claude Code, opencode, and any MCP-compatible client
+
+## Requirements
+
+- Node.js ≥ 18
+
+## Quick start
+
+No installation needed:
+
+```bash
+npx agent-memory-store
+```
+
+With a custom storage path:
+
+```bash
+AGENT_STORE_PATH=/your/project/.agent-memory-store npx agent-memory-store
+```
+
+## Configuration
+
+### Claude Code
+
+Add to your project's `claude.mcp.json` (or `~/.claude/claude.mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "agent-memory-store": {
+      "command": "npx",
+      "args": ["-y", "agent-memory-store"],
+      "env": {
+        "AGENT_STORE_PATH": "/your/project/.agent-memory-store"
+      }
+    }
+  }
+}
+```
+
+Or using the Claude Code CLI:
+
+```bash
+claude mcp add agent-memory-store \
+  --command "npx" \
+  --args "-y agent-memory-store" \
+  --env "AGENT_STORE_PATH=/your/project/.agent-memory-store"
+```
+
+### opencode
+
+Add to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "agent-memory-store": {
+      "command": "npx",
+      "args": ["-y", "agent-memory-store"],
+      "env": {
+        "AGENT_STORE_PATH": "/your/project/.agent-memory-store"
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code (MCP extension)
+
+Add to your MCP settings file:
+
+```json
+{
+  "servers": {
+    "agent-memory-store": {
+      "command": "npx",
+      "args": ["-y", "agent-memory-store"],
+      "env": {
+        "AGENT_STORE_PATH": "/your/project/.agent-memory-store"
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable           | Default                 | Description                            |
+| ------------------ | ----------------------- | -------------------------------------- |
+| `AGENT_STORE_PATH` | `./.agent-memory-store` | Absolute path to the storage directory |
+
+## Tools
+
+| Tool             | When to use                                                               |
+| ---------------- | ------------------------------------------------------------------------- |
+| `search_context` | **Start of every task** — retrieve relevant prior knowledge before acting |
+| `write_context`  | After decisions, discoveries, or outputs that other agents will need      |
+| `read_context`   | Read a specific chunk by ID                                               |
+| `list_context`   | Inventory the memory store (metadata only, no body)                       |
+| `delete_context` | Remove outdated or incorrect chunks                                       |
+| `get_state`      | Read a pipeline variable (progress, flags, counters)                      |
+| `set_state`      | Write a pipeline variable                                                 |
+
+### `search_context`
+
+```
+query      string    Search query. Use specific, canonical terms.
+tags       string[]  (optional) Narrow to chunks matching any of these tags.
+agent      string    (optional) Narrow to chunks written by a specific agent.
+top_k      number    (optional) Max results to return. Default: 6.
+min_score  number    (optional) Minimum BM25 score. Default: 0.1.
+```
+
+### `write_context`
+
+```
+topic       string    Short, specific title. ("Auth — JWT decision", not "decision")
+content     string    Chunk body in markdown. Include rationale, not just conclusions.
+agent       string    (optional) Agent ID writing this chunk.
+tags        string[]  (optional) Canonical tags for future retrieval.
+importance  string    (optional) low | medium | high | critical. Default: medium.
+ttl_days    number    (optional) Auto-expiry in days. Omit for permanent storage.
+```
+
+### `get_state` / `set_state`
+
+```
+key    string   State variable name.
+value  any      (set_state only) Any JSON-serializable value.
+```
+
+## Storage format
+
+Each chunk is a plain `.md` file under `.context/chunks/`:
+
+```markdown
+---
+id: a3f9c12b40
+topic: "Auth service — chose JWT over sessions"
+agent: architect-agent
+tags: [auth, architecture, decision]
+importance: high
+updated: 2025-06-01T14:32:00.000Z
+---
+
+Chose stateless JWT over server-side sessions.
+
+**Rationale:** No shared session store needed across services.
+Refresh tokens stored in Redis with 7-day TTL.
+Access tokens expire in 15 minutes.
+
+**Trade-offs:** Cannot invalidate individual tokens before expiry.
+Acceptable for our threat model.
+```
+
+Session state lives in `.agent-memory-store/state/<key>.json`.
+
+Both directories are human-readable, diffable with git, and can be committed to version control if you want shared team memory.
+
+## Agent system prompt
+
+Paste this into the system prompt of every agent that should use the memory store:
+
+```markdown
+## Memory usage
+
+You have access to a persistent local memory store via agent-memory-store MCP tools.
+
+**At the start of each task:**
+
+1. Call `search_context` with 2–3 specific queries related to what you are about to do.
+2. Incorporate retrieved chunks (score > 1.0) into your reasoning.
+3. Call `get_state` to check pipeline status if relevant.
+
+**After completing a subtask:**
+
+1. Call `write_context` to persist:
+   - Decisions made and their rationale
+   - Key discoveries or findings
+   - Structured outputs intended for downstream agents
+2. Use canonical tags consistent with the rest of the team.
+3. Set `importance: high` or `critical` for information other agents will need.
+
+**Best practices:**
+
+- Specific topics: "ZAP scraper — stack decision" > "decision"
+- Consistent tags: always use the same term (`auth`, not `authentication` or `autenticação`)
+- Check before writing: search first to avoid duplicate chunks
+- Temporary context: use `ttl_days: 7` for session-scoped information
+```
+
+## How BM25 search works
+
+BM25 ranks documents by term frequency and inverse document frequency, normalized by document length. It is the ranking algorithm behind Elasticsearch and Apache Lucene.
+
+**Strengths:**
+
+- Works well for short, labeled text chunks
+- Instant — no network calls, no GPU, no warm-up
+- Deterministic and explainable
+
+**Limitations:**
+
+- No semantic understanding (`car` ≠ `automobile`)
+- Mitigated by using canonical tags and consistent terminology across agents
+
+**Score interpretation:**
+
+- `> 3.0` — strong match, highly relevant
+- `1.0 – 3.0` — good match, likely relevant
+- `0.1 – 1.0` — weak match, may be tangentially related
+- `< 0.1` — filtered out by default
+
+## Development
+
+```bash
+git clone https://github.com/YOUR_USERNAME/agent-memory-store
+cd agent-memory-store
+npm install
+npm start
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## Project structure
+
+```
+src/
+  bm25.js      BM25 ranking engine — pure JS, zero dependencies
+  store.js     File-based persistence (chunks + session state)
+  index.js     MCP server and tool definitions
+```
+
+## Roadmap
+
+- [ ] `summarize_context` tool — LLM-powered chunk consolidation
+- [ ] `prune_context` tool — remove chunks by age, agent, or importance
+- [ ] Hybrid scoring: BM25 + optional local embedding reranking (ollama)
+- [ ] Web UI for browsing the memory store
+- [ ] Multi-project workspace support
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "agent-memory-store",
+  "version": "0.0.1",
+  "description": "Local-first MCP memory server for multi-agent systems. BM25 search, zero external dependencies, file-based persistence.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "context-store": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test src/__tests__/store.test.js",
+    "lint": "node --check src/bm25.js src/store.js src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "multi-agent",
+    "memory",
+    "rag",
+    "bm25",
+    "context",
+    "opencode",
+    "claude",
+    "llm"
+  ],
+  "author": "Vinícius Barreto",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vbfs/context-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vbfs/context-store/issues"
+  },
+  "homepage": "https://github.com/vbfs/context-store#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "gray-matter": "^4.0.3",
+    "zod": "^4.3.6"
+  }
+}

package/src/bm25.js

@@ -0,0 +1,115 @@
+/**
+ * BM25 (Best Match 25) ranking algorithm — pure JavaScript implementation.
+ *
+ * BM25 is a bag-of-words retrieval function that ranks documents by relevance
+ * to a given query. It is the default ranking algorithm in Elasticsearch and
+ * Apache Lucene, and works exceptionally well for short, well-labeled text
+ * chunks without requiring any external APIs or embedding models.
+ *
+ * Tuning parameters:
+ *   k1 (1.5) — term frequency saturation. Higher = more weight on rare terms.
+ *   b  (0.75) — length normalization. 1.0 = full normalization, 0 = none.
+ */
+
+const k1 = 1.5;
+const b = 0.75;
+
+/**
+ * Tokenizes a string into lowercase terms, stripping punctuation.
+ * Handles Latin extended characters (Portuguese, Spanish, French, etc.).
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^\w\s]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length > 1);
+}
+
+export class BM25 {
+  constructor() {
+    /** @type {Array<{ id: string, len: number, metadata: object }>} */
+    this.documents = [];
+    /** @type {Array<Map<string, number>>} */
+    this.termFreqs = [];
+    /** @type {Map<string, number>} term → document frequency */
+    this.docFreqs = new Map();
+    this.avgLen = 0;
+  }
+
+  /**
+   * Adds a document to the index.
+   *
+   * @param {string} id       - Unique document identifier
+   * @param {string} text     - Searchable text content
+   * @param {object} metadata - Arbitrary metadata attached to results
+   */
+  addDocument(id, text, metadata = {}) {
+    const tokens = tokenize(text);
+    const tf = new Map();
+    for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
+
+    this.documents.push({ id, len: tokens.length, metadata });
+    this.termFreqs.push(tf);
+
+    for (const term of tf.keys()) {
+      this.docFreqs.set(term, (this.docFreqs.get(term) || 0) + 1);
+    }
+
+    const total = this.documents.reduce((s, d) => s + d.len, 0);
+    this.avgLen = total / this.documents.length;
+  }
+
+  /**
+   * Computes the BM25 score for a single document against query terms.
+   *
+   * @param {number}   docIdx
+   * @param {string[]} queryTerms
+   * @returns {number}
+   */
+  _score(docIdx, queryTerms) {
+    const doc = this.documents[docIdx];
+    const tf = this.termFreqs[docIdx];
+    const N = this.documents.length;
+    let score = 0;
+
+    for (const term of queryTerms) {
+      const freq = tf.get(term) || 0;
+      if (freq === 0) continue;
+      const df = this.docFreqs.get(term) || 0;
+      const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+      const tfNorm =
+        (freq * (k1 + 1)) / (freq + k1 * (1 - b + b * (doc.len / this.avgLen)));
+      score += idf * tfNorm;
+    }
+    return score;
+  }
+
+  /**
+   * Searches the index and returns the top-K most relevant documents.
+   *
+   * @param {string}   query         - Natural language search query
+   * @param {number}   [topK=5]      - Maximum results to return
+   * @param {Function} [filter=null] - Optional predicate fn(metadata) => boolean
+   * @returns {Array<{ id: string, score: number, metadata: object }>}
+   */
+  search(query, topK = 5, filter = null) {
+    const queryTerms = tokenize(query);
+    const results = [];
+
+    for (let i = 0; i < this.documents.length; i++) {
+      const doc = this.documents[i];
+      if (filter && !filter(doc.metadata)) continue;
+      const score = this._score(i, queryTerms);
+      if (score > 0)
+        results.push({ id: doc.id, score, metadata: doc.metadata });
+    }
+
+    return results.sort((a, b) => b.score - a.score).slice(0, topK);
+  }
+}

package/src/index.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * agent-store MCP server entry point.
+ *
+ * Exposes 7 tools to any MCP-compatible client (Claude Code, opencode, etc.):
+ *   search_context  — BM25 full-text search over stored chunks
+ *   write_context   — persist a new memory chunk
+ *   read_context    — retrieve a chunk by ID
+ *   list_context    — list chunk metadata (no body)
+ *   delete_context  — remove a chunk by ID
+ *   get_state       — read a session state variable
+ *   set_state       — write a session state variable
+ *
+ * Usage:
+ *   npx @agentops/context-store
+ *   CONTEXT_STORE_PATH=/your/project/.context npx @agentops/context-store
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  searchChunks,
+  writeChunk,
+  readChunk,
+  deleteChunk,
+  listChunks,
+  getState,
+  setState,
+} from "./store.js";
+
+const { version } = JSON.parse(
+  await import("fs").then((fs) =>
+    fs.promises.readFile(new URL("../package.json", import.meta.url), "utf8"),
+  ),
+);
+
+const server = new McpServer({
+  name: "context-store",
+  version,
+});
+
+// ─── search_context ───────────────────────────────────────────────────────────
+
+server.tool(
+  "search_context",
+  [
+    "Search stored memory chunks by relevance using BM25 full-text ranking.",
+    "Call this at the start of any task to retrieve relevant prior knowledge,",
+    "decisions, and outputs before generating a response.",
+  ].join(" "),
+  {
+    query: z
+      .string()
+      .describe(
+        "Search query. Be specific — use canonical terms your team agreed on.",
+      ),
+    tags: z
+      .array(z.string())
+      .optional()
+      .describe("Narrow results to chunks matching any of these tags."),
+    agent: z
+      .string()
+      .optional()
+      .describe("Narrow results to chunks written by a specific agent ID."),
+    top_k: z
+      .number()
+      .int()
+      .min(1)
+      .max(20)
+      .optional()
+      .describe("Maximum number of results to return (default: 6)."),
+    min_score: z
+      .number()
+      .min(0)
+      .optional()
+      .describe(
+        "Minimum BM25 relevance score. Lower = more permissive (default: 0.1).",
+      ),
+  },
+  async ({ query, tags, agent, top_k, min_score }) => {
+    const results = await searchChunks({
+      query,
+      tags: tags ?? [],
+      agent,
+      topK: top_k ?? 6,
+      minScore: min_score ?? 0.1,
+    });
+
+    if (results.length === 0) {
+      return { content: [{ type: "text", text: "No matching chunks found." }] };
+    }
+
+    const body = results
+      .map((r) =>
+        [
+          `### [score: ${r.score}] ${r.topic}`,
+          `**id:** \`${r.id}\` | **agent:** ${r.agent} | **tags:** ${r.tags.join(", ")} | **importance:** ${r.importance} | **updated:** ${r.updated}`,
+          "",
+          r.content,
+        ].join("\n"),
+      )
+      .join("\n\n---\n\n");
+
+    return { content: [{ type: "text", text: body }] };
+  },
+);
+
+// ─── write_context ────────────────────────────────────────────────────────────
+
+server.tool(
+  "write_context",
+  [
+    "Persist a memory chunk to local storage.",
+    "Call this after completing a subtask, making a key decision,",
+    "or producing output that downstream agents will need.",
+  ].join(" "),
+  {
+    topic: z
+      .string()
+      .describe(
+        'Short, specific title. e.g. "Auth service — JWT decision" not "decision".',
+      ),
+    content: z
+      .string()
+      .describe(
+        "Chunk body in markdown. Include rationale, not just conclusions.",
+      ),
+    agent: z
+      .string()
+      .optional()
+      .describe(
+        'Agent ID writing this chunk (e.g. "pm-agent", "scraper-agent").',
+      ),
+    tags: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Canonical tags for future retrieval. Use consistent terms across agents.",
+      ),
+    importance: z
+      .enum(["low", "medium", "high", "critical"])
+      .optional()
+      .describe(
+        "Importance level — affects future curation decisions (default: medium).",
+      ),
+    ttl_days: z
+      .number()
+      .positive()
+      .optional()
+      .describe("Auto-expiry in days. Omit for permanent storage."),
+  },
+  async ({ topic, content, agent, tags, importance, ttl_days }) => {
+    const result = await writeChunk({
+      topic,
+      content,
+      agent: agent ?? "global",
+      tags: tags ?? [],
+      importance: importance ?? "medium",
+      ttlDays: ttl_days,
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Chunk saved: id=\`${result.id}\` | topic="${result.topic}" | tags=[${result.tags.join(", ")}] | importance=${result.importance}`,
+        },
+      ],
+    };
+  },
+);
+
+// ─── read_context ─────────────────────────────────────────────────────────────
+
+server.tool(
+  "read_context",
+  "Retrieve the full content of a specific chunk by its ID.",
+  {
+    id: z
+      .string()
+      .describe(
+        "Chunk ID (10-char hex string from write_context or list_context).",
+      ),
+  },
+  async ({ id }) => {
+    const chunk = await readChunk(id);
+
+    if (!chunk) {
+      return {
+        content: [{ type: "text", text: `No chunk found with id \`${id}\`.` }],
+      };
+    }
+
+    const { meta, content } = chunk;
+    const header = [
+      `## ${meta.topic}`,
+      `**id:** \`${meta.id}\` | **agent:** ${meta.agent} | **tags:** ${(meta.tags || []).join(", ")} | **importance:** ${meta.importance} | **updated:** ${meta.updated}`,
+    ].join("\n");
+
+    return { content: [{ type: "text", text: `${header}\n\n${content}` }] };
+  },
+);
+
+// ─── list_context ─────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_context",
+  "List all stored chunks (metadata only, no body). Useful for inventory and curation.",
+  {
+    agent: z.string().optional().describe("Filter by agent ID."),
+    tags: z.array(z.string()).optional().describe("Filter by tags."),
+  },
+  async ({ agent, tags }) => {
+    const chunks = await listChunks({ agent, tags: tags ?? [] });
+
+    if (chunks.length === 0) {
+      return { content: [{ type: "text", text: "Memory store is empty." }] };
+    }
+
+    const lines = chunks.map(
+      (c) =>
+        `- \`${c.id}\` **${c.topic}** | agent:${c.agent} | tags:[${c.tags.join(", ")}] | ${c.importance} | ${c.updated}`,
+    );
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${chunks.length} chunk(s) found:\n\n${lines.join("\n")}`,
+        },
+      ],
+    };
+  },
+);
+
+// ─── delete_context ───────────────────────────────────────────────────────────
+
+server.tool(
+  "delete_context",
+  "Permanently delete a chunk by ID. Use to remove outdated or incorrect memory.",
+  {
+    id: z.string().describe("Chunk ID to delete."),
+  },
+  async ({ id }) => {
+    const deleted = await deleteChunk(id);
+    return {
+      content: [
+        {
+          type: "text",
+          text: deleted
+            ? `Chunk \`${id}\` deleted.`
+            : `No chunk found with id \`${id}\`.`,
+        },
+      ],
+    };
+  },
+);
+
+// ─── get_state ────────────────────────────────────────────────────────────────
+
+server.tool(
+  "get_state",
+  "Read a pipeline state variable by key. Use to check progress, flags, and counters across agent turns.",
+  {
+    key: z.string().describe("State key to read."),
+  },
+  async ({ key }) => {
+    const value = await getState(key);
+
+    if (value === null) {
+      return {
+        content: [{ type: "text", text: `State key "${key}" not found.` }],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            typeof value === "string" ? value : JSON.stringify(value, null, 2),
+        },
+      ],
+    };
+  },
+);
+
+// ─── set_state ────────────────────────────────────────────────────────────────
+
+server.tool(
+  "set_state",
+  "Write a pipeline state variable (any JSON-serializable value). Use to track progress, store flags, or pass structured data between agent turns.",
+  {
+    key: z
+      .string()
+      .describe('State key (e.g. "pipeline_status", "current_phase").'),
+    value: z.any().describe("Any JSON-serializable value."),
+  },
+  async ({ key, value }) => {
+    const result = await setState(key, value);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `State "${key}" written at ${result.updated}.`,
+        },
+      ],
+    };
+  },
+);
+
+// ─── Start server ─────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/store.js

@@ -0,0 +1,292 @@
+/**
+ * context-store: file-based persistent memory for multi-agent systems.
+ *
+ * Storage layout:
+ *   <CONTEXT_STORE_PATH>/
+ *     chunks/   → one .md file per chunk, YAML frontmatter + markdown body
+ *     state/    → one .json file per key (session state / pipeline variables)
+ *
+ * Chunk file format:
+ *   ---
+ *   id: <sha1-10>
+ *   topic: "Descriptive title of the chunk"
+ *   agent: agent-id
+ *   tags: [tag1, tag2]
+ *   importance: low | medium | high | critical
+ *   updated: ISO-8601
+ *   expires: ISO-8601   # optional — omit for permanent chunks
+ *   ---
+ *   Markdown content here.
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import matter from "gray-matter";
+import { createHash } from "crypto";
+import { BM25 } from "./bm25.js";
+
+const STORE_PATH = process.env.CONTEXT_STORE_PATH
+  ? path.resolve(process.env.CONTEXT_STORE_PATH)
+  : path.join(process.cwd(), ".context");
+
+const CHUNKS_DIR = path.join(STORE_PATH, "chunks");
+const STATE_DIR = path.join(STORE_PATH, "state");
+
+/** Ensures storage directories exist. */
+async function ensureDirs() {
+  await fs.mkdir(CHUNKS_DIR, { recursive: true });
+  await fs.mkdir(STATE_DIR, { recursive: true });
+}
+
+/**
+ * Generates a stable short ID from agent + topic + current timestamp.
+ * @param {string} agentId
+ * @param {string} topic
+ * @returns {string} 10-char hex string
+ */
+function generateId(agentId, topic) {
+  const seed = `${agentId}:${topic}:${Date.now()}:${Math.random()}`;
+  return createHash("sha1").update(seed).digest("hex").slice(0, 10);
+}
+
+/**
+ * Reads all non-expired chunks from disk.
+ * Expired chunks are automatically deleted on read.
+ *
+ * @returns {Promise<Array<{ file: string, meta: object, content: string }>>}
+ */
+async function loadAllChunks() {
+  await ensureDirs();
+  const files = await fs.readdir(CHUNKS_DIR).catch(() => []);
+  const chunks = [];
+
+  await Promise.all(
+    files.map(async (file) => {
+      if (!file.endsWith(".md")) return;
+      try {
+        const raw = await fs.readFile(path.join(CHUNKS_DIR, file), "utf8");
+        const { data: meta, content } = matter(raw);
+
+        if (meta.expires && new Date(meta.expires) < new Date()) {
+          await fs.unlink(path.join(CHUNKS_DIR, file)).catch(() => {});
+          return;
+        }
+
+        chunks.push({ file, meta, content: content.trim() });
+      } catch {
+        // Skip unreadable files silently
+      }
+    }),
+  );
+
+  return chunks;
+}
+
+/**
+ * Builds a BM25 index from a list of chunks.
+ * Searchable text = topic + tags + agent + body content.
+ *
+ * @param {Array} chunks
+ * @returns {BM25}
+ */
+function buildIndex(chunks) {
+  const engine = new BM25();
+  for (const c of chunks) {
+    const searchText = [
+      c.meta.topic || "",
+      (c.meta.tags || []).join(" "),
+      c.meta.agent || "",
+      c.content,
+    ].join(" ");
+    engine.addDocument(c.file, searchText, c.meta);
+  }
+  return engine;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Searches chunks by relevance using BM25, with optional tag and agent filters.
+ *
+ * @param {object} opts
+ * @param {string}   opts.query     - Search query text
+ * @param {string[]} [opts.tags]    - Filter: only chunks matching any of these tags
+ * @param {string}   [opts.agent]   - Filter: only chunks written by this agent
+ * @param {number}   [opts.topK]    - Max results (default: 6)
+ * @param {number}   [opts.minScore] - Minimum BM25 score threshold (default: 0.1)
+ * @returns {Promise<Array>}
+ */
+export async function searchChunks({
+  query,
+  tags = [],
+  agent,
+  topK = 6,
+  minScore = 0.1,
+}) {
+  const chunks = await loadAllChunks();
+  if (chunks.length === 0) return [];
+
+  const engine = buildIndex(chunks);
+  const hasFilter = tags.length > 0 || !!agent;
+
+  const filter = hasFilter
+    ? (meta) => {
+        if (agent && meta.agent !== agent) return false;
+        if (tags.length > 0 && !tags.some((t) => (meta.tags || []).includes(t)))
+          return false;
+        return true;
+      }
+    : null;
+
+  const hits = engine.search(query, topK, filter);
+  const byFile = Object.fromEntries(chunks.map((c) => [c.file, c]));
+
+  return hits
+    .filter((h) => h.score >= minScore)
+    .map((h) => {
+      const c = byFile[h.id];
+      return {
+        id: c.meta.id,
+        topic: c.meta.topic,
+        agent: c.meta.agent,
+        tags: c.meta.tags || [],
+        importance: c.meta.importance || "medium",
+        score: Math.round(h.score * 100) / 100,
+        content: c.content,
+        updated: c.meta.updated,
+      };
+    });
+}
+
+/**
+ * Writes a new chunk to disk.
+ *
+ * @param {object} opts
+ * @param {string}   opts.topic      - Short descriptive title
+ * @param {string}   opts.content    - Markdown body content
+ * @param {string}   [opts.agent]    - Agent identifier
+ * @param {string[]} [opts.tags]     - Search tags
+ * @param {string}   [opts.importance] - low | medium | high | critical
+ * @param {number}   [opts.ttlDays]  - Days until auto-expiry (omit = permanent)
+ * @returns {Promise<{ id, file, topic, tags, importance }>}
+ */
+export async function writeChunk({
+  topic,
+  content,
+  agent = "global",
+  tags = [],
+  importance = "medium",
+  ttlDays = null,
+}) {
+  await ensureDirs();
+
+  const id = generateId(agent, topic);
+  const now = new Date().toISOString();
+  const expires = ttlDays
+    ? new Date(Date.now() + ttlDays * 86_400_000).toISOString()
+    : null;
+
+  const meta = {
+    id,
+    topic,
+    agent,
+    tags,
+    importance,
+    updated: now,
+    ...(expires ? { expires } : {}),
+  };
+
+  const fileContent = matter.stringify(`\n${content}\n`, meta);
+  const filename = `${id}.md`;
+
+  await fs.writeFile(path.join(CHUNKS_DIR, filename), fileContent, "utf8");
+  return { id, file: filename, topic, tags, importance };
+}
+
+/**
+ * Reads a single chunk by its ID.
+ *
+ * @param {string} id
+ * @returns {Promise<{ meta: object, content: string } | null>}
+ */
+export async function readChunk(id) {
+  const chunks = await loadAllChunks();
+  return chunks.find((c) => c.meta.id === id) ?? null;
+}
+
+/**
+ * Deletes a chunk by ID.
+ *
+ * @param {string} id
+ * @returns {Promise<boolean>} true if deleted, false if not found
+ */
+export async function deleteChunk(id) {
+  const chunks = await loadAllChunks();
+  const target = chunks.find((c) => c.meta.id === id);
+  if (!target) return false;
+  await fs.unlink(path.join(CHUNKS_DIR, target.file));
+  return true;
+}
+
+/**
+ * Lists chunk metadata without loading full content.
+ * Results are sorted by most recently updated.
+ *
+ * @param {object}   opts
+ * @param {string}   [opts.agent]
+ * @param {string[]} [opts.tags]
+ * @returns {Promise<Array>}
+ */
+export async function listChunks({ agent, tags = [] } = {}) {
+  const chunks = await loadAllChunks();
+  return chunks
+    .filter((c) => {
+      if (agent && c.meta.agent !== agent) return false;
+      if (tags.length > 0 && !tags.some((t) => (c.meta.tags || []).includes(t)))
+        return false;
+      return true;
+    })
+    .map((c) => ({
+      id: c.meta.id,
+      topic: c.meta.topic,
+      agent: c.meta.agent,
+      tags: c.meta.tags || [],
+      importance: c.meta.importance || "medium",
+      updated: c.meta.updated,
+    }))
+    .sort((a, b) => new Date(b.updated) - new Date(a.updated));
+}
+
+/**
+ * Reads a session state variable.
+ *
+ * @param {string} key
+ * @returns {Promise<any | null>}
+ */
+export async function getState(key) {
+  await ensureDirs();
+  try {
+    const raw = await fs.readFile(path.join(STATE_DIR, `${key}.json`), "utf8");
+    return JSON.parse(raw).value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes a session state variable (any JSON-serializable value).
+ *
+ * @param {string} key
+ * @param {any}    value
+ * @returns {Promise<{ key: string, updated: string }>}
+ */
+export async function setState(key, value) {
+  await ensureDirs();
+  const updated = new Date().toISOString();
+  await fs.writeFile(
+    path.join(STATE_DIR, `${key}.json`),
+    JSON.stringify({ key, value, updated }, null, 2),
+    "utf8",
+  );
+  return { key, updated };
+}