@tekmemo/fs

@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