@tekmemo/fs

Node.js filesystem adapter for TekMemo's canonical .tekmemo/ local memory protocol.

This package implements the core MemoryStore interface from tekmemo using the local filesystem.

Canonical layout

When used with bootstrapMemoryStore, this adapter writes:

.tekmemo/
  manifest.json
  memory/
    core.md
    notes.md
  events/
    memory-events.jsonl
    conversations.jsonl
  indexes/
    chunks.jsonl
  graph/
    nodes.jsonl
    edges.jsonl
  snapshots/
    snapshots.jsonl

Quickstart

import { bootstrapMemoryStore, writeCoreMemory } from "tekmemo";
import { createNodeFsMemoryStore } from "@tekmemo/fs";

const store = createNodeFsMemoryStore({
  rootDir: process.cwd()
});

await bootstrapMemoryStore(store);
await writeCoreMemory(store, "# Core Memory\n\n- Local-first memory is enabled.\n");

Options

| Option | Default | Description | |---|---:|---| | rootDir | required | Project directory where .tekmemo/ will live | | createRoot | true | Create the root directory if missing | | missingFileBehavior | "throw" | Throw or return empty string when reading missing files | | disallowSymlinks | true | Reject symlinked paths under .tekmemo/ | | directoryMode | 0o700 | Directory mode for created directories | | fileMode | 0o600 | File mode for created files |

Safety behavior

This adapter provides:

• safe path resolution under rootDir
• canonical .tekmemo/ path validation through tekmemo
• parent directory creation
• atomic writes
• same-instance append serialization
• symlink rejection by default
• missing-file behavior control

Missing files

Strict mode:

const store = createNodeFsMemoryStore({ rootDir });
await store.read(".tekmemo/memory/core.md"); // throws if missing

Relaxed mode:

const store = createNodeFsMemoryStore({
  rootDir,
  missingFileBehavior: "empty"
});

await store.read(".tekmemo/memory/core.md"); // "" if missing