Reading & Writing Memory

Core memory operations, classified memory writes, notes, conversation logging, and document helpers in @memofs/core.

@memofs/core provides high-level client methods on MemoFS as well as standalone document functions to read, write, and append memory across canonical files.

Writing Classified Memories

memofs.writeMemory() is the primary entry point for recording new agent insights, decisions, and constraints. It automatically runs durability classification, write-blocklist validation, and graph extraction.

const result = await memofs.writeMemory({
  title: "Authentication Standard",
  content: "All internal service-to-service calls must use mTLS with Ed25519 certificates.",
  kind: "decision",
  tags: ["security", "auth", "networking"],
  confidence: 0.95,
  writer: "security-team@example.com",
  anchor: {
    file: "src/auth/mtls.ts",
    hash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  },
});

console.log(result.id);          // "mem_abc123"
console.log(result.created);     // true
console.log(result.tier);        // "durable" (or "transient")
console.log(result.tierReason);  // "durable-kind"

Parameters

Field	Type	Required	Description
`content`	`string`	Yes	The markdown memory text body.
`title`	`string`	No	Optional human-readable title for the note header.
`kind`	`MemoryKind`	No	Memory kind: `"decision" \| "constraint" \| "goal" \| "preference" \| "reference" \| "summary" \| "note"`.
`tags`	`string[]`	No	Array of category tags (e.g. `["auth", "api"]`).
`confidence`	`number`	No	Confidence score between `0` and `1`. Confidence `< 0.4` triggers transient classification.
`source`	`string`	No	Source identifier (e.g. `"pr-128"`, `"slack-thread"`).
`writer`	`string`	No	Human or agent attribution (e.g. `"alice@corp.com"`, `"claude-code"`).
`id`	`string`	No	Stable memory ID override (useful for deterministic connector sync).
`idempotencyKey`	`string`	No	Idempotency token to prevent duplicate writes on network retries.
`tier`	`"durable" \| "transient"`	No	Explicit durability tier override.
`anchor`	`AnchorRef`	No	Source code file anchor (`file`, `hash`, optional `symbol`) for drift detection.
`sourceRefs`	`SourceRef[]`	No	Granular external source references.
`metadata`	`JsonObject`	No	Arbitrary JSON metadata attached to the record.

Return Value

interface WriteMemoryResult {
  id: string;                      // Generated or provided memory ID
  created: boolean;                // False if deduplicated by idempotencyKey
  tier: "durable" | "transient";   // Final durability tier
  tierReason: DurabilityReason;    // Why the classifier chose this tier
  sourceRefs?: SourceRef[];        // Preserved source references
  warnings?: string[];             // Any non-fatal warnings
}

Core Memory

Core memory (.memofs/memory/core.md) stores concise, permanent workspace truths that should be loaded into active agent prompts:

// Read core memory (returns raw markdown string)
const coreMarkdown = await memofs.core.read();
console.log(coreMarkdown);

// Overwrite core memory with updated rules
await memofs.core.update(`# Project Rules

- Always use TypeScript strict mode.
- Use Bun for local scripts and Node 22 for production runtime.
- Never commit credentials to git.
`);

Notes Memory

Notes memory (.memofs/memory/notes.md) stores long-form timestamped entries:

// Read entire notes file
const notes = await memofs.notes.read();

// Record a timestamped note
await memofs.notes.record({
  title: "PostgreSQL Migration",
  content: "Migrated user session tables from Redis to Postgres partitioned tables.",
  kind: "decision",
  tags: ["database", "migration"],
  confidence: 1.0,
});

Conversations

Conversations (.memofs/events/conversations.jsonl) logs interaction history for historical analysis:

// Append a conversation turn
await memofs.conversations.append({
  timestamp: new Date().toISOString(),
  role: "user",
  content: "How do we handle rate limiting in the API?",
  summary: "User asked about rate limiting architecture",
});

// Read the last 20 entries
const history = await memofs.conversations.read();
console.log(history.slice(-20));

Listing Recent Events

Query recent memory operations from .memofs/events/memory-events.jsonl:

const recent = await memofs.listRecentMemories({ limit: 10 });
for (const item of recent.items) {
  console.log(`[${item.timestamp}] ${item.type}: ${item.summary}`);
}

Standalone Document Helpers

For low-level operations or custom storage backends, @memofs/core exports pure helper functions that operate directly against any MemoryStore:

import {
  readCoreMemory,
  writeCoreMemory,
  readNotesMemory,
  appendTimestampedNote,
  readConversationHistory,
  appendConversationEntry,
  readMemoryEvents,
  appendMemoryEvent,
  InMemoryMemoryStore,
} from "@memofs/core";

// 1. Initialize any storage adapter implementing MemoryStore
const store = new InMemoryMemoryStore();

// 2. Direct document operations
await writeCoreMemory(store, "# Workspace Rules\n- Enforce strict typing\n");
const coreText = await readCoreMemory(store);
console.log(coreText);

// 3. Append timestamped note
await appendTimestampedNote(store, {
  timestamp: new Date().toISOString(),
  kind: "decision",
  content: "Refactored payment gateway handler to support Stripe and PayPal.",
});

// 4. Read notes
const notesText = await readNotesMemory(store);
console.log(notesText);

Reading & Writing Memory

On this page