opencode-fractal-memory 0.4.0 → 0.4.2

package/README.md

@@ -60,11 +60,11 @@ Add the plugin name to `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "plugins": ["opencode-fractal-memory"]
+  "plugin": ["opencode-fractal-memory"]
 }
 ```
 
-OpenCode installs it automatically at startup. Model files (~24 MB) download on first plugin load via `ensureModels()` — no manual steps needed.
+OpenCode installs it automatically at startup from npm. Model files (~24 MB) download on first plugin load via `ensureModels()` — no manual steps needed.
 
 ### For development / manual install
 
@@ -317,6 +317,9 @@ Skills are specialized instruction sets stored as memory nodes. When a task matc
 | `svelte-core-bestpractices` | svelte, component, runes |
 | `svelte-code-writer` | svelte 5, sveltekit, component |
 | `customize-opencode` | opencode config, agent, plugin |
+| `context-engineering` | context, prompt, system message |
+| `git-workflow-and-versioning` | git, commit, branch, version, publish |
+| `incremental-implementation` | step by step, increment, gradual |
 
 ### Loading a skill
 
@@ -410,13 +413,20 @@ When OpenCode loads the plugin, `initStorage()` runs automatically:
 6. **Background embeddings** — after 1s, generates embeddings for nodes that lack them
 7. **Auto-retrieve hook** — if enabled in config, injects relevant context into prompts
 
+Every initialization step is logged with timing in `logs/memory-plugin.log`, making it easy to diagnose startup issues.
+
 All of this happens automatically — no manual intervention required.
 
 ## Logs
 
+All plugin logs are consolidated under `~/.config/opencode/logs/`:
+
 | Log | Path | Contents |
 |-----|------|----------|
-| Memory | `~/.config/opencode/memory.log` | Plugin operations, errors, injection events |
+| Plugin | `logs/memory-plugin.log` | Plugin operations, init steps with timing, auto-retrieve, session events |
+| MCP server | `logs/mcp-server.log` | MCP tool calls, resources, errors |
+| Injection debug | `logs/memory-injection.log` | Full auto-retrieve injection payloads (rotated at 1 MB) |
+| Context dump | `logs/context-dump.log` | Full context snapshots for debugging |
 | OpenCode | `~/.local/share/opencode/log/` | Application lifecycle, tool calls |
 
 ## Development

package/dist/hooks/auto-retrieve/index.js

@@ -7,7 +7,13 @@ import { scoreCandidates } from "./scoring";
 import { detectRelevantSkills, detectRelevantPlaybooks } from "./detection";
 import { formatPlaybooksAsAvailable, formatSkillsAsAvailable } from "./formatting";
 import { formatNodeForInjection } from "./content";
-const INJECTION_LOG_FILE = path.join(os.homedir(), ".config", "opencode", "memory-injection.log");
+const INJECTION_LOG_DIR = path.join(os.homedir(), ".config", "opencode", "logs");
+const INJECTION_LOG_FILE = path.join(INJECTION_LOG_DIR, "memory-injection.log");
+const INJECTION_LOG_MAX_SIZE = 1024 * 1024;
+try {
+    fs.mkdirSync(INJECTION_LOG_DIR, { recursive: true });
+}
+catch { }
 export function createAutoRetrieveHook(deps) {
     const { store, config, log } = deps;
     const autoConfig = config.autoRetrieve;
@@ -136,6 +142,13 @@ ${JSON.stringify(memoriesJson, null, 2)}
                     return;
                 const debugLine = `[${new Date().toISOString()}] Query: ${userText.slice(0, 100)}...\n${fullBlock}\n\n`;
                 try {
+                    try {
+                        const stat = fs.statSync(INJECTION_LOG_FILE);
+                        if (stat.size > INJECTION_LOG_MAX_SIZE) {
+                            fs.renameSync(INJECTION_LOG_FILE, INJECTION_LOG_FILE + ".old");
+                        }
+                    }
+                    catch { }
                     fs.appendFileSync(INJECTION_LOG_FILE, debugLine);
                 }
                 catch { /* silent fail */ }

package/dist/logging.js

@@ -1,9 +1,14 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-const LOG_FILE = path.join(os.homedir(), ".config", "opencode", "memory-plugin.log");
-const CONTEXT_DUMP_FILE = path.join(os.homedir(), ".config", "opencode", "context_dump.log");
+const LOG_DIR = path.join(os.homedir(), ".config", "opencode", "logs");
+const LOG_FILE = path.join(LOG_DIR, "memory-plugin.log");
+const CONTEXT_DUMP_FILE = path.join(LOG_DIR, "context-dump.log");
 const MAX_LOG_SIZE = 5 * 1024 * 1024;
+try {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+}
+catch { }
 let currentSessionId = null;
 let logLevel = "info";
 // Categories to always skip (OpenCode core noise)

package/dist/mcp/logging.js

@@ -1,8 +1,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-const MCP_LOG_FILE = path.join(os.homedir(), ".config", "opencode", "fractal-memory-server.log");
+const MCP_LOG_DIR = path.join(os.homedir(), ".config", "opencode", "logs");
+const MCP_LOG_FILE = path.join(MCP_LOG_DIR, "mcp-server.log");
 const MAX_LOG_SIZE = 1024 * 1024;
+try {
+    fs.mkdirSync(MCP_LOG_DIR, { recursive: true });
+}
+catch { }
 export function mcpLog(level, msg, data) {
     try {
         const ts = new Date().toISOString().slice(0, 19).replace("T", " ");

package/dist/mcp/server.js

@@ -11,7 +11,9 @@ const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../package.json"), "utf-8"));
 let store;
 export async function createMemoryMcpServer(projectDir, globalDbPath) {
+    mcpLog("info", "Creating memory store", { projectDir });
     store = createSqliteMemoryStore(projectDir, globalDbPath);
+    mcpLog("info", "Memory store created");
     const server = new McpServer({ name: "opencode-fractal-memory", version: pkg.version }, { capabilities: { tools: {}, resources: {} } });
     server.registerTool("memory_search", {
         description: "Search memory nodes by text, embedding similarity, or BM25 score",

package/dist/plugin/index.js

@@ -1,15 +1,32 @@
 import { initStorage, loadPluginConfig, seedRuleNodes, backfillData, scheduleBackgroundEmbeddings, setupJournal, startManagementIfEnabled, createAutoRetrieveIfEnabled } from "./init";
 import { createHookHandlers } from "./hooks";
 import { createToolMap } from "./tools";
+import { memLog, perfNow } from "../logging";
 export const MemoryPlugin = async (ctx) => {
     const { directory, client } = ctx;
+    const t0 = perfNow();
+    memLog("info", "init", "Plugin initialization started", { directory });
+    let t = perfNow();
     const store = await initStorage(directory);
+    memLog("info", "init", "Storage initialized", { durationMs: perfNow() - t });
+    t = perfNow();
     const memConfig = await loadPluginConfig(directory);
+    memLog("info", "init", "Config loaded", { durationMs: perfNow() - t });
+    t = perfNow();
     await seedRuleNodes(store);
+    memLog("info", "init", "Seed nodes completed", { durationMs: perfNow() - t });
+    t = perfNow();
     await backfillData(store);
+    memLog("info", "init", "Backfill completed", { durationMs: perfNow() - t });
+    t = perfNow();
     scheduleBackgroundEmbeddings(store);
+    memLog("info", "init", "Background embeddings scheduled", { durationMs: perfNow() - t });
+    t = perfNow();
     const journalTools = await setupJournal(directory);
+    memLog("info", "init", "Journal setup completed", { durationMs: perfNow() - t });
+    t = perfNow();
     startManagementIfEnabled(store, directory);
+    memLog("info", "init", "Management server check completed", { durationMs: perfNow() - t });
     const ruleCache = new Map();
     const ruleCacheDirty = { value: true };
     const sessionInjectionLock = new Map();
@@ -17,6 +34,7 @@ export const MemoryPlugin = async (ctx) => {
     const autoRetrieveHook = createAutoRetrieveIfEnabled(store, memConfig);
     const handlers = createHookHandlers(store, client, memConfig, ruleCache, ruleCacheDirty, sessionInjectionLock, latestUserMessage);
     const toolMap = createToolMap(store, journalTools, client);
+    memLog("info", "init", "Plugin initialization completed", { totalDurationMs: perfNow() - t0 });
     return {
         ...handlers,
         ...(autoRetrieveHook || {}),

package/dist/plugin/init.js

@@ -12,10 +12,15 @@ import { memLog } from "../logging";
 import { setCacheConfig } from "../cache";
 import { setHighContextThreshold, setCriticalContextThreshold, setMaxInjectionTokens, setCoreInjectionTokens, setAutoCompressThreshold } from "./state";
 export async function initStorage(directory) {
+    memLog("info", "init", "Creating memory store", { directory });
     const store = createMemoryStore(directory);
+    memLog("info", "init", "Ensuring seed nodes");
     await store.ensureSeed();
+    memLog("info", "init", "Ensuring models");
     await ensureModels();
+    memLog("info", "init", "Ensuring agent files");
     await ensureAgentFiles().catch(() => { });
+    memLog("info", "init", "Ensuring command files");
     await ensureCommandFiles().catch(() => { });
     return store;
 }
@@ -31,6 +36,7 @@ export async function loadPluginConfig(directory) {
     return memConfig;
 }
 export async function seedRuleNodes(store) {
+    let created = 0;
     for (const seed of SEED_NODES) {
         try {
             await store.getNodeByLabel("global", seed.label);
@@ -48,15 +54,21 @@ export async function seedRuleNodes(store) {
                 importance: 1,
                 metadata: seed.metadata ?? null,
             });
+            created++;
         }
     }
+    memLog("info", "init", "Seed nodes checked", { total: SEED_NODES.length, created });
 }
 export async function backfillData(store) {
     for (const scope of ["global", "project"]) {
+        memLog("info", "init", `Backfilling links for ${scope}`);
         await store.backfillLinks(scope);
+        memLog("info", "init", `Backfilling embeddings and BM25 for ${scope}`);
         await store.backfillBinaryEmbeddingsAndBM25(scope);
     }
+    memLog("info", "init", "Rebuilding HNSW index");
     await store.rebuildHNSWIndex();
+    memLog("info", "init", "HNSW index rebuilt");
 }
 export function scheduleBackgroundEmbeddings(store) {
     setTimeout(async () => {
@@ -94,9 +106,13 @@ export function startManagementIfEnabled(store, directory) {
     loadConfig().then(c => {
         const mgmtConfig = c.management;
         if (mgmtConfig?.enabled === true) {
+            memLog("info", "init", "Starting management server", { port: mgmtConfig.port ?? 8787 });
             startManagementServer(store, directory, { enabled: true, port: mgmtConfig?.port ?? 8787 });
         }
-    }).catch(() => { });
+        else {
+            memLog("info", "init", "Management server disabled");
+        }
+    }).catch(() => { memLog("info", "init", "Management server config not available"); });
 }
 export function createAutoRetrieveIfEnabled(store, memConfig) {
     return memConfig?.autoRetrieve?.enabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-fractal-memory",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Fractal memory system for OpenCode with semantic search and automatic compression.",
   "main": "dist/plugin.js",
   "type": "module",