@akalsey/openclaw-memory 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# openclaw-memory
+
+A per-turn-lean memory plugin. Small always-loaded core, explicit on-demand retrieval. Memory is markdown files on disk, search is BM25, and the corpus stays manageable through deliberate writes rather than passive capture.
+
+---
+
+## Setup
+
+### Install
+
+```bash
+openclaw plugins install local:/path/to/openclaw-memory
+```
+
+### Configuration
+
+```json
+{
+  "plugins": {
+    "memory": {
+      "memoryPath": "~/.openclaw/memory",
+      "search": {
+        "defaultLimit": 5,
+        "maxLimit": 20,
+        "recencyBoostDays": 30,
+        "recencyBoostMax": 1.2
+      },
+      "write": {
+        "requireTags": true,
+        "minTags": 1,
+        "maxTags": 12
+      }
+    }
+  }
+}
+```
+
+All settings are optional — defaults above are used if omitted.
+
+### Storage layout
+
+```
+~/.openclaw/memory/
+├── indexed/
+│   ├── 2026-05-20-posthog-billing-a3f9b2c1.md
+│   └── ...
+└── _searches.json
+```
+
+Memories are plain markdown files. You can read, edit, and grep them in any editor. External edits are picked up automatically via filesystem watching.
+
+---
+
+## Memory entry format
+
+```markdown
+---
+id: mem_2026-05-20_a3f9b2c1
+created: 2026-05-20T14:30:00Z
+updated: 2026-05-20T14:30:00Z
+tags: [posthog, billing, group-identify]
+source: session
+score: 0.7
+size_tier: full
+last_accessed: 2026-05-20T14:30:00Z
+access_count: 3
+---
+
+# PostHog group identify billing investigation
+
+PostHog charges separately for groupIdentify events under the data warehouse
+SKU. Our May 2026 spike traced to a deploy that called groupIdentify on every
+page view. Fix: call it once per session, cache client-side.
+```
+
+---
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `memory_search(query, tags?, limit?)` | BM25 search, returns excerpts + metadata |
+| `memory_get(id)` | Full content of one entry; updates access metadata |
+| `memory_write(content, tags)` | Creates new entry, returns id |
+| `memory_supersede(old_id, new_content, new_tags, reason)` | Replaces outdated entry |
+| `memory_stats()` | Corpus stats: count, size, top tags, recent activity |
+| `memory_recent_searches(limit?)` | Last N searches with result counts |
+
+---
+
+## Using it effectively
+
+The agent learns when to search from the SKILL.md that ships with the plugin. Key behaviors to reinforce:
+
+- When core memory has a pointer to indexed memory → agent searches before answering
+- After an investigation produces findings → agent writes a memory entry
+- When a memory contradicts current knowledge → agent supersedes rather than leaving conflicts
+
+**Tags are the most important thing you control.** The agent writes them at creation time. Good tags are terms you'd type in a future search: domain names, topic words, project names. Sparse tags make recall worse; there's no downside to 8 tags if they're all relevant.
+
+---
+
+## Inspecting memory
+
+```bash
+# How many entries, top tags
+openclaw memory stats
+
+# Recent searches and their result counts
+openclaw memory recent-searches
+
+# Browse entries directly
+ls ~/.openclaw/memory/indexed/
+grep -l "billing" ~/.openclaw/memory/indexed/
+cat ~/.openclaw/memory/indexed/2026-05-20-posthog-billing-a3f9b2c1.md
+```
+
+---
+
+## Troubleshooting
+
+**Agent answers from training data instead of memory**
+The agent didn't search. Check the SKILL.md is loading (visible in session start). Add explicit pointers in core memory: "Indexed memory has notes on [topic]." This gives the agent a concrete cue to search.
+
+**Search returns nothing for a topic you know exists**
+Try different query terms — BM25 is lexical, not semantic. If the entry uses different vocabulary than your query, it won't match. Check what terms are in the actual entry with `grep`. Add more tags when you write entries.
+
+**Index out of sync after external edits**
+The chokidar watcher picks up external file changes in real time. If it seems stale, restart the OpenClaw session to force a full reload.
+
+**Corpus growing too large**
+v1 has no automatic decay. Prune manually by deleting files from `~/.openclaw/memory/indexed/` or using `memory_supersede` to replace bulky entries with summaries. Semantic search + decay-as-pruning is planned for v2.
+
+**Duplicate or contradictory entries**
+Use `memory_supersede`. It deletes the old entry and creates a new one, appending the reason for traceability. Nothing in v1 detects contradictions automatically — the agent notices during retrieval and resolves them on encountering them.

package/SKILL.md

@@ -0,0 +1,44 @@
+# Using openclaw-memory
+
+You have two layers of memory:
+
+**Core memory** — always loaded, broad strokes. Entries may include pointers like "Indexed memory has detailed notes on X." These pointers are your cue to search.
+
+**Indexed memory** — searchable, detail-rich, not loaded by default. Six tools:
+
+- `memory_search(query, tags?, limit?)` — BM25 search, returns excerpts
+- `memory_get(id)` — load full content of one entry
+- `memory_write(content, tags, title?, source?)` — create a new entry, returns id
+- `memory_supersede(old_id, new_content, new_tags, reason)` — replace outdated entry
+- `memory_stats()` — corpus statistics
+- `memory_recent_searches(limit?)` — recent queries and their result counts
+
+## When to search
+
+- Core memory has a pointer to indexed memory on this topic → search before answering
+- Task requires procedural specifics, code, or prior investigation details → search first
+- User asks "what do you know about X?" → search before falling back to training data
+- You're about to do something and you know past sessions touched this domain → search for prior notes
+
+## When to write
+
+- You learn something procedural or specific that will be useful in a future session
+- An investigation produced findings that shouldn't be re-run from scratch
+- A decision was made with non-obvious reasoning that future sessions should know
+- A correction was made that reveals a domain-specific rule
+
+**Tag generously.** Use terms you'd plausibly type in a future search. Domain names (posthog, github, salesforce), topic words (billing, funnel, merge, deploy), project names, people's names.
+
+## How to query
+
+Write queries as natural phrases, not keyword lists. "PostHog billing spike investigation" works better than "posthog billing." Include terms from the likely entry body, not just the likely title.
+
+## The contradiction rule
+
+If you retrieve a memory that contradicts a newer source or your current knowledge, use `memory_supersede` rather than leaving conflicting entries in the corpus. The reason field is logged; be specific about what changed and why.
+
+## When not to search
+
+- Simple factual questions well-covered by training data
+- Quick conversational exchanges
+- Questions where core memory already gives you what you need

package/dist/index.js

@@ -0,0 +1 @@
+export { default } from "./src/service.js";

package/dist/src/bm25.js

@@ -0,0 +1,58 @@
+const K1 = 1.5;
+const B = 0.75;
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .split(/\s+/)
+        .filter(t => t.length > 1);
+}
+export function buildCorpus(docs) {
+    const docMap = new Map();
+    const df = new Map();
+    let totalLength = 0;
+    for (const doc of docs) {
+        const tokens = tokenize(doc.text);
+        const tf = new Map();
+        for (const token of tokens)
+            tf.set(token, (tf.get(token) ?? 0) + 1);
+        docMap.set(doc.id, { tf, length: tokens.length });
+        totalLength += tokens.length;
+        for (const term of tf.keys())
+            df.set(term, (df.get(term) ?? 0) + 1);
+    }
+    return {
+        docs: docMap,
+        df,
+        N: docs.length,
+        avgdl: docs.length > 0 ? totalLength / docs.length : 0,
+    };
+}
+export function scoreDoc(corpus, docId, queryTokens) {
+    const doc = corpus.docs.get(docId);
+    if (!doc)
+        return 0;
+    let score = 0;
+    for (const term of queryTokens) {
+        const freq = doc.tf.get(term) ?? 0;
+        if (freq === 0)
+            continue;
+        const df = corpus.df.get(term) ?? 0;
+        const idf = Math.log((corpus.N - df + 0.5) / (df + 0.5) + 1);
+        const tfNorm = (freq * (K1 + 1)) / (freq + K1 * (1 - B + B * (doc.length / corpus.avgdl)));
+        score += idf * tfNorm;
+    }
+    return score;
+}
+export function search(corpus, query) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0)
+        return [];
+    const results = [];
+    for (const id of corpus.docs.keys()) {
+        const score = scoreDoc(corpus, id, queryTokens);
+        if (score > 0)
+            results.push({ id, score });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}

package/dist/src/entry-parser.js

@@ -0,0 +1,26 @@
+import matter from "gray-matter";
+import { extractTitle } from "./utils.js";
+export function parseEntry(raw, filename) {
+    const parsed = matter(raw);
+    const fm = parsed.data;
+    const body = parsed.content.trim();
+    const slug = filename.replace(/\.md$/, "").replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    return {
+        id: fm.id ?? "",
+        created: fm.created ?? new Date().toISOString(),
+        updated: fm.updated ?? new Date().toISOString(),
+        tags: Array.isArray(fm.tags) ? fm.tags : [],
+        source: (fm.source ?? "manual"),
+        score: fm.score ?? 0.5,
+        size_tier: (fm.size_tier ?? "full"),
+        last_accessed: fm.last_accessed ?? new Date().toISOString(),
+        access_count: fm.access_count ?? 0,
+        title: extractTitle(body, slug),
+        body,
+        filename,
+    };
+}
+export function serializeEntry(entry) {
+    const { title: _title, body, filename: _filename, ...fm } = entry;
+    return matter.stringify("\n" + body, fm);
+}

package/dist/src/index-store.js

@@ -0,0 +1,57 @@
+import { loadAllEntries } from "./storage.js";
+import { buildCorpus } from "./bm25.js";
+import { searchEntries } from "./search.js";
+export class IndexStore {
+    entries = new Map();
+    corpus = { docs: new Map(), df: new Map(), N: 0, avgdl: 0 };
+    async loadFromDirectory(indexedDir) {
+        const all = await loadAllEntries(indexedDir);
+        this.entries.clear();
+        for (const entry of all)
+            this.entries.set(entry.id, entry);
+        this.rebuildCorpus();
+    }
+    rebuildCorpus() {
+        const docs = [...this.entries.values()].map(e => ({
+            id: e.id,
+            text: `${e.title} ${e.title} ${e.tags.join(" ")} ${e.tags.join(" ")} ${e.body}`,
+        }));
+        this.corpus = buildCorpus(docs);
+    }
+    add(entry) {
+        this.entries.set(entry.id, entry);
+        this.rebuildCorpus();
+    }
+    update(entry) {
+        this.entries.set(entry.id, entry);
+        this.rebuildCorpus();
+    }
+    removeById(id) {
+        this.entries.delete(id);
+        this.rebuildCorpus();
+    }
+    removeByFilename(filename) {
+        for (const [id, entry] of this.entries) {
+            if (entry.filename === filename) {
+                this.entries.delete(id);
+                break;
+            }
+        }
+        this.rebuildCorpus();
+    }
+    getAll() {
+        return [...this.entries.values()];
+    }
+    getById(id) {
+        return this.entries.get(id);
+    }
+    getCorpus() {
+        return this.corpus;
+    }
+    size() {
+        return this.entries.size;
+    }
+    search(input, recencyBoostDays, recencyBoostMax, defaultLimit, maxLimit) {
+        return searchEntries(this.getAll(), this.corpus, input, recencyBoostDays, recencyBoostMax, defaultLimit, maxLimit);
+    }
+}

package/dist/src/search.js

@@ -0,0 +1,59 @@
+import { tokenize, search as bm25Search } from "./bm25.js";
+function extractExcerpt(body, queryTokens, maxLength = 200) {
+    if (body.length <= maxLength)
+        return body;
+    const lower = body.toLowerCase();
+    let bestPos = 0;
+    for (const token of queryTokens) {
+        const pos = lower.indexOf(token);
+        if (pos >= 0) {
+            bestPos = pos;
+            break;
+        }
+    }
+    const start = Math.max(0, bestPos - 60);
+    const end = Math.min(body.length, start + maxLength);
+    const excerpt = body.slice(start, end).trim();
+    return (start > 0 ? "…" : "") + excerpt + (end < body.length ? "…" : "");
+}
+function recencyBoost(createdAt, boostDays, maxBoost) {
+    const ageDays = (Date.now() - new Date(createdAt).getTime()) / 86_400_000;
+    if (ageDays >= boostDays)
+        return 1.0;
+    return 1.0 + (maxBoost - 1.0) * (1 - ageDays / boostDays);
+}
+function accessBoost(accessCount) {
+    return 1.0 + Math.min(0.1, accessCount * 0.01);
+}
+export function searchEntries(entries, corpus, input, recencyBoostDays, recencyBoostMax, defaultLimit, maxLimit) {
+    const limit = Math.min(input.limit ?? defaultLimit, maxLimit);
+    const tagFilter = input.tags?.map(t => t.toLowerCase()) ?? [];
+    let candidates = entries;
+    if (tagFilter.length > 0) {
+        candidates = entries.filter(e => tagFilter.every(tag => e.tags.map(t => t.toLowerCase()).includes(tag)));
+    }
+    const candidateIds = new Set(candidates.map(e => e.id));
+    const entryMap = new Map(entries.map(e => [e.id, e]));
+    const bm25Results = bm25Search(corpus, input.query).filter(r => candidateIds.has(r.id));
+    const queryTokens = tokenize(input.query);
+    const boosted = bm25Results
+        .map(r => {
+        const entry = entryMap.get(r.id);
+        const score = r.score
+            * recencyBoost(entry.created, recencyBoostDays, recencyBoostMax)
+            * accessBoost(entry.access_count);
+        return { entry, score };
+    })
+        .sort((a, b) => b.score - a.score);
+    const totalMatched = boosted.length;
+    const results = boosted.slice(0, limit).map(({ entry, score }) => ({
+        id: entry.id,
+        title: entry.title,
+        excerpt: extractExcerpt(entry.body, queryTokens),
+        tags: entry.tags,
+        created: entry.created,
+        score,
+        size_tier: entry.size_tier,
+    }));
+    return { results, total_matched: totalMatched };
+}

package/dist/src/service.js

@@ -0,0 +1,199 @@
+import { mkdir } from "fs/promises";
+import { join, basename } from "path";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { DEFAULT_CONFIG } from "./types.js";
+import { resolveDataPath, generateId, generateFilename, extractTitle } from "./utils.js";
+import { writeEntry, deleteEntry } from "./storage.js";
+import { IndexStore } from "./index-store.js";
+import { computeStats, loadSearchLog, appendSearchLog } from "./stats.js";
+function mergeConfig(raw, workspaceDir) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...raw,
+        memoryPath: resolveDataPath(raw.memoryPath, workspaceDir, DEFAULT_CONFIG.memoryPath),
+        search: { ...DEFAULT_CONFIG.search, ...(raw.search ?? {}) },
+        write: { ...DEFAULT_CONFIG.write, ...(raw.write ?? {}) },
+    };
+}
+export default definePluginEntry({
+    id: "memory",
+    name: "Memory",
+    description: "Per-turn-lean memory: small core + on-demand BM25 indexed retrieval",
+    async register(api) {
+        const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(api.pluginConfig);
+        const config = mergeConfig(api.pluginConfig, workspaceDir);
+        const indexedDir = join(config.memoryPath, "indexed");
+        const searchLogPath = join(config.memoryPath, "_searches.json");
+        await mkdir(indexedDir, { recursive: true });
+        const store = new IndexStore();
+        await store.loadFromDirectory(indexedDir);
+        const { watch } = await import("chokidar");
+        const watcher = watch(indexedDir, { ignoreInitial: true });
+        watcher
+            .on("add", async (filePath) => {
+            const filename = basename(filePath);
+            if (!filename.endsWith(".md"))
+                return;
+            const { readEntry } = await import("./storage.js");
+            store.add(await readEntry(indexedDir, filename));
+        })
+            .on("change", async (filePath) => {
+            const filename = basename(filePath);
+            if (!filename.endsWith(".md"))
+                return;
+            const { readEntry } = await import("./storage.js");
+            store.update(await readEntry(indexedDir, filename));
+        })
+            .on("unlink", (filePath) => {
+            store.removeByFilename(basename(filePath));
+        });
+        api.registerTool({
+            name: "memory_search",
+            description: "Search indexed memory. Returns titles, excerpts, tags. Call memory_get for full content.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Free-text search query" },
+                    tags: { type: "array", items: { type: "string" }, description: "Require ALL of these tags (AND semantics)" },
+                    limit: { type: "number", description: "Max results to return (default 5, max 20)" },
+                },
+                required: ["query"],
+            },
+            async execute(_id, params) {
+                const input = params;
+                const output = store.search(input, config.search.recencyBoostDays, config.search.recencyBoostMax, config.search.defaultLimit, config.search.maxLimit);
+                await appendSearchLog({
+                    query: input.query,
+                    tags: input.tags,
+                    result_count: output.total_matched,
+                    timestamp: new Date().toISOString(),
+                }, searchLogPath);
+                return { content: [{ type: "text", text: JSON.stringify(output) }] };
+            },
+        });
+        api.registerTool({
+            name: "memory_get",
+            description: "Load the full content of a memory entry by id. Updates access metadata.",
+            parameters: {
+                type: "object",
+                properties: { id: { type: "string" } },
+                required: ["id"],
+            },
+            async execute(_id, params) {
+                const { id } = params;
+                const entry = store.getById(id);
+                if (!entry) {
+                    return { content: [{ type: "text", text: JSON.stringify({ error: `Entry ${id} not found` }) }] };
+                }
+                const updated = {
+                    ...entry,
+                    last_accessed: new Date().toISOString(),
+                    access_count: entry.access_count + 1,
+                };
+                await writeEntry(indexedDir, updated);
+                store.update(updated);
+                return { content: [{ type: "text", text: JSON.stringify({
+                                id: updated.id, title: updated.title, content: updated.body,
+                                tags: updated.tags, created: updated.created, updated: updated.updated,
+                                source: updated.source, size_tier: updated.size_tier,
+                                last_accessed: updated.last_accessed, access_count: updated.access_count,
+                            }) }] };
+            },
+        });
+        api.registerTool({
+            name: "memory_write",
+            description: "Write a new memory entry. Returns the new entry's id.",
+            parameters: {
+                type: "object",
+                properties: {
+                    content: { type: "string", description: "Markdown body" },
+                    tags: { type: "array", items: { type: "string" }, description: "Tags for this entry (required)" },
+                    title: { type: "string", description: "Optional title override; derived from first H1 if absent" },
+                    source: { type: "string", description: "Origin: session | dreams | manual | import" },
+                },
+                required: ["content", "tags"],
+            },
+            async execute(_id, params) {
+                const input = params;
+                if (config.write.requireTags && input.tags.length < config.write.minTags) {
+                    return { content: [{ type: "text", text: JSON.stringify({ error: `At least ${config.write.minTags} tag required` }) }] };
+                }
+                if (input.tags.length > config.write.maxTags) {
+                    return { content: [{ type: "text", text: JSON.stringify({ error: `Maximum ${config.write.maxTags} tags allowed` }) }] };
+                }
+                const now = new Date().toISOString();
+                const id = generateId();
+                const title = input.title ?? extractTitle(input.content, id);
+                const filename = generateFilename(id, title);
+                const entry = {
+                    id, created: now, updated: now, tags: input.tags,
+                    source: input.source ?? "session",
+                    score: 0.5, size_tier: "full",
+                    last_accessed: now, access_count: 0,
+                    title, body: input.content, filename,
+                };
+                await writeEntry(indexedDir, entry);
+                store.add(entry);
+                return { content: [{ type: "text", text: JSON.stringify({ id }) }] };
+            },
+        });
+        api.registerTool({
+            name: "memory_supersede",
+            description: "Replace an outdated memory entry with new content. Old entry is deleted; reason is appended to new entry.",
+            parameters: {
+                type: "object",
+                properties: {
+                    old_id: { type: "string" },
+                    new_content: { type: "string" },
+                    new_tags: { type: "array", items: { type: "string" } },
+                    reason: { type: "string" },
+                },
+                required: ["old_id", "new_content", "new_tags", "reason"],
+            },
+            async execute(_id, params) {
+                const input = params;
+                const old = store.getById(input.old_id);
+                if (!old) {
+                    return { content: [{ type: "text", text: JSON.stringify({ error: `Entry ${input.old_id} not found` }) }] };
+                }
+                await deleteEntry(indexedDir, old.filename);
+                store.removeById(input.old_id);
+                const now = new Date().toISOString();
+                const id = generateId();
+                const body = input.new_content + `\n\n---\n*Supersedes ${input.old_id}: ${input.reason}*`;
+                const title = extractTitle(body, id);
+                const filename = generateFilename(id, title);
+                const entry = {
+                    id, created: now, updated: now, tags: input.new_tags,
+                    source: "session", score: 0.5, size_tier: "full",
+                    last_accessed: now, access_count: 0,
+                    title, body, filename,
+                };
+                await writeEntry(indexedDir, entry);
+                store.add(entry);
+                return { content: [{ type: "text", text: JSON.stringify({ new_id: id }) }] };
+            },
+        });
+        api.registerTool({
+            name: "memory_stats",
+            description: "Return statistics about the memory corpus: entry count, size, top tags, recent activity.",
+            parameters: { type: "object", properties: {} },
+            async execute(_id, _params) {
+                return { content: [{ type: "text", text: JSON.stringify(computeStats(store.getAll())) }] };
+            },
+        });
+        api.registerTool({
+            name: "memory_recent_searches",
+            description: "Return recent search queries with result counts, for tuning and gap analysis.",
+            parameters: {
+                type: "object",
+                properties: { limit: { type: "number", description: "Number of recent searches to return (default 20)" } },
+            },
+            async execute(_id, params) {
+                const { limit = 20 } = (params ?? {});
+                const log = await loadSearchLog(searchLogPath);
+                return { content: [{ type: "text", text: JSON.stringify(log.slice(-limit)) }] };
+            },
+        });
+    },
+});

package/dist/src/stats.js

@@ -0,0 +1,47 @@
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+export function computeStats(entries) {
+    const now = Date.now();
+    const sevenDays = 7 * 86_400_000;
+    const tagCounts = new Map();
+    let totalSizeBytes = 0;
+    let totalTokens = 0;
+    let createdRecently = 0;
+    let accessedRecently = 0;
+    for (const e of entries) {
+        totalSizeBytes += e.body.length + 200;
+        totalTokens += e.body.split(/\s+/).filter(Boolean).length;
+        for (const tag of e.tags)
+            tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+        if (now - new Date(e.created).getTime() < sevenDays)
+            createdRecently++;
+        if (now - new Date(e.last_accessed).getTime() < sevenDays)
+            accessedRecently++;
+    }
+    const top_tags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 20)
+        .map(([tag, count]) => ({ tag, count }));
+    return {
+        total_entries: entries.length,
+        total_size_bytes: totalSizeBytes,
+        avg_tokens_per_entry: entries.length > 0 ? Math.round(totalTokens / entries.length) : 0,
+        top_tags,
+        created_last_7_days: createdRecently,
+        accessed_last_7_days: accessedRecently,
+    };
+}
+export async function loadSearchLog(logPath) {
+    try {
+        return JSON.parse(await readFile(logPath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+export async function appendSearchLog(entry, logPath, maxEntries = 50) {
+    const log = await loadSearchLog(logPath);
+    const updated = [...log, entry].slice(-maxEntries);
+    await mkdir(dirname(logPath), { recursive: true });
+    await writeFile(logPath, JSON.stringify(updated, null, 2), "utf-8");
+}

package/dist/src/storage.js

@@ -0,0 +1,27 @@
+import { readFile, writeFile, unlink, readdir } from "fs/promises";
+import { join } from "path";
+import { parseEntry, serializeEntry } from "./entry-parser.js";
+import { MEMORY_FILENAME_PATTERN } from "./utils.js";
+export async function readEntry(indexedDir, filename) {
+    const raw = await readFile(join(indexedDir, filename), "utf-8");
+    return parseEntry(raw, filename);
+}
+export async function writeEntry(indexedDir, entry) {
+    await writeFile(join(indexedDir, entry.filename), serializeEntry(entry), "utf-8");
+}
+export async function deleteEntry(indexedDir, filename) {
+    await unlink(join(indexedDir, filename));
+}
+export async function listEntryFilenames(indexedDir) {
+    try {
+        const files = await readdir(indexedDir);
+        return files.filter(f => MEMORY_FILENAME_PATTERN.test(f)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function loadAllEntries(indexedDir) {
+    const filenames = await listEntryFilenames(indexedDir);
+    return Promise.all(filenames.map(f => readEntry(indexedDir, f)));
+}

package/dist/src/types.js

@@ -0,0 +1,14 @@
+export const DEFAULT_CONFIG = {
+    memoryPath: "memory",
+    search: {
+        defaultLimit: 5,
+        maxLimit: 20,
+        recencyBoostDays: 30,
+        recencyBoostMax: 1.2,
+    },
+    write: {
+        requireTags: true,
+        minTags: 1,
+        maxTags: 12,
+    },
+};

package/dist/src/utils.js

@@ -0,0 +1,38 @@
+import { homedir } from "os";
+import { join } from "path";
+import { randomBytes } from "crypto";
+export function resolvePath(p) {
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+}
+export function resolveDataPath(override, workspaceDir, defaultRelative) {
+    if (!override)
+        return join(workspaceDir, defaultRelative);
+    if (override.startsWith('/') || override.startsWith('~/'))
+        return resolvePath(override);
+    return join(workspaceDir, override);
+}
+export function generateId(date = new Date()) {
+    const dateStr = date.toISOString().slice(0, 10);
+    const suffix = randomBytes(4).toString("hex");
+    return `mem_${dateStr}_${suffix}`;
+}
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .slice(0, 60)
+        .replace(/^-|-$/g, "");
+}
+export function generateFilename(id, title, date = new Date()) {
+    const dateStr = date.toISOString().slice(0, 10);
+    const slug = slugify(title) || "untitled";
+    const suffix = id.slice(-8);
+    return `${dateStr}-${slug}-${suffix}.md`;
+}
+export function extractTitle(body, fallback) {
+    const match = body.match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim() ?? fallback;
+}
+export const MEMORY_FILENAME_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z0-9-]+-[a-z0-9]{8}\.md$/;

package/openclaw.plugin.json

@@ -0,0 +1,14 @@
+{
+  "id": "memory",
+  "name": "Memory",
+  "version": "0.1.0",
+  "description": "Per-turn-lean memory: small always-loaded core + on-demand BM25 search over indexed markdown files",
+  "contracts": {
+    "tools": ["memory_search", "memory_get", "memory_write", "memory_supersede", "memory_stats", "memory_recent_searches"]
+  },
+  "activation": { "onStartup": true },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@akalsey/openclaw-memory",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "install": {
+      "localPath": "."
+    }
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "latest",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.24-beta.2"
+  }
+}