MemoFS

https://memofs.dev
Admin
MemoFS is a file-first memory runtime for AI agents that stores versioned, portable memory as plain...
Tokens:41,454
Snippets:607
Trust Score:7.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Claude Code Setup

Source: https://docs.memofs.dev/packages/cli/generate

Example command for a complete Claude Code setup including rules, hooks, and MCP configuration.

```bash
memofs generate agent claude --project-name "My App"
```

--------------------------------

### Clone and Install Project

Source: https://docs.memofs.dev/community/contributing

Initial steps to clone the repository and install dependencies.

```bash
git clone https://github.com/memo-fs/memofs.git
cd memofs
pnpm install
pnpm validate:workspace
```

--------------------------------

### Install @memofs/adapter-r2

Source: https://docs.memofs.dev/packages/adapters/r2

Installation commands for various package managers.

```sh
npm install @memofs/adapter-r2
```

```sh
pnpm add @memofs/adapter-r2
```

```sh
yarn add @memofs/adapter-r2
```

```sh
bun add @memofs/adapter-r2
```

```sh
deno add npm:@memofs/adapter-r2
```

--------------------------------

### Install @memofs/adapter-ai-sdk

Source: https://docs.memofs.dev/packages/adapters/ai-sdk

Installation commands for various package managers.

```sh
npm install @memofs/adapter-ai-sdk
```

```sh
pnpm add @memofs/adapter-ai-sdk
```

```sh
yarn add @memofs/adapter-ai-sdk
```

```sh
bun add @memofs/adapter-ai-sdk
```

```sh
bun add npm:@memofs/adapter-ai-sdk
```

--------------------------------

### Install Benchmark Kit

Source: https://docs.memofs.dev/packages/benchmark-kit

Installation commands for various package managers.

```sh
npm install -D @memofs/benchmark-kit
```

```sh
pnpm add -D @memofs/benchmark-kit
```

```sh
yarn add -D @memofs/benchmark-kit
```

```sh
bun add -d @memofs/benchmark-kit
```

--------------------------------

### Install @memofs/adapter-transformers

Source: https://docs.memofs.dev/packages/adapters/transformers

Installation commands for various package managers.

```sh
npm install @memofs/adapter-transformers
```

```sh
pnpm add @memofs/adapter-transformers
```

```sh
yarn add @memofs/adapter-transformers
```

```sh
bun add @memofs/adapter-transformers
```

```sh
deno add npm:@memofs/adapter-transformers
```

--------------------------------

### Install @memofs/core

Source: https://docs.memofs.dev/packages/core

Install the core package using your preferred package manager.

```sh
npm install @memofs/core
```

```sh
pnpm add @memofs/core
```

```sh
yarn add @memofs/core
```

```sh
bun add @memofs/core
```

```sh
deno add npm:@memofs/core
```

--------------------------------

### Example configuration file

Source: https://docs.memofs.dev/packages/cli

A sample .memofs/config.json file structure.

```json
{
  "$schema": "../node_modules/@memofs/cli/schema/config.json",
  "runtime": "hybrid",
  "root": ".",
  "cloud": {
    "baseUrl": "https://memofs.dev/api/v1",
    "projectId": "pro_abc123"
  },
  "recall": {
    "engine": "hybrid",
    "localEmbeddings": true
  }
}
```

--------------------------------

### Install @memofs/server

Source: https://docs.memofs.dev/packages/server

Commands to install the server package using various package managers.

```sh
npm install @memofs/server
```

```sh
pnpm add @memofs/server
```

```sh
yarn add @memofs/server
```

```sh
bun add @memofs/server
```

```sh
deno add npm:@memofs/server
```

--------------------------------

### Install CLI globally

Source: https://docs.memofs.dev/packages/cli

Install the CLI tool globally on the system.

```sh
npm install -g @memofs/cli
```

```sh
pnpm add -g @memofs/cli
```

```sh
yarn global add @memofs/cli
```

```sh
bun add -g @memofs/cli
```

```sh
deno install --global -A npm:@memofs/cli
```

--------------------------------

### Boot the server

Source: https://docs.memofs.dev/packages/server/node

Command to start the server with a specific port.

```bash
PORT=8787 memofs-server
```

--------------------------------

### Initialize Memofs in a project

Source: https://docs.memofs.dev/blog/the-memory-layer-for-any-ai-agent

Install the CLI, scaffold the configuration directory, and generate agent hooks.

```bash
npm i -g @memofs/cli           # the runtime
npx memofs init                # scaffold .memofs/ in your project
memofs generate agent claude   # wire up hooks + MCP for your agent
```

--------------------------------

### Install OpenAI Adapter

Source: https://docs.memofs.dev/packages/adapters/openai

Commands to install the adapter package using various package managers.

```sh
npm install @memofs/adapter-openai
```

```sh
pnpm add @memofs/adapter-openai
```

```sh
yarn add @memofs/adapter-openai
```

```sh
bun add @memofs/adapter-openai
```

```sh
deno add npm:@memofs/adapter-openai
```

--------------------------------

### Initialize MemoFS and Run Connectors

Source: https://docs.memofs.dev/packages/connectors

Setup the MemoFS store and execute connectors using the EnvSecretResolver.

```ts
import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";
import { runConnectors, EnvSecretResolver } from "@memofs/connectors";

const store = createNodeFsMemoryStore({ rootDir: "." });
const memo = new MemoFS({ store, projectId: "my-app" });

const result = await runConnectors({
  rootDir: ".",
  memo,
  secretResolver: new EnvSecretResolver({ rootDir: "." }),
});

console.log(result.written); // ["conn_...", ...] — newly ingested note ids
console.log(result.skipped); // ["issue:42", ...] — already ingested (dedup)
console.log(result.errors);  // per-connector recoverable errors
console.log(result.ran);     // ["github-main", ...] — connector ids that ran this pass
```

--------------------------------

### Install MemoFS Connectors

Source: https://docs.memofs.dev/packages/connectors

Commands to install the required packages using various package managers.

```sh
npm install @memofs/connectors @memofs/core
```

```sh
pnpm add @memofs/connectors @memofs/core
```

```sh
yarn add @memofs/connectors @memofs/core
```

```sh
bun add @memofs/connectors @memofs/core
```

--------------------------------

### Install memofs-server globally

Source: https://docs.memofs.dev/packages/server/node

Commands to install the server binary globally using various package managers.

```sh
npm install -g @memofs/server
```

```sh
pnpm add -g @memofs/server
```

```sh
yarn global add @memofs/server
```

```sh
bun add -g @memofs/server
```

```deno
deno install -g --allow-all npm:@memofs/server
```

--------------------------------

### Install Turso Adapter

Source: https://docs.memofs.dev/packages/adapters/turso

Commands to install the @memofs/adapter-turso package using various package managers.

```sh
npm install @memofs/adapter-turso
```

```sh
pnpm add @memofs/adapter-turso
```

```sh
yarn add @memofs/adapter-turso
```

```sh
bun add @memofs/adapter-turso
```

```sh
deno add npm:@memofs/adapter-turso
```

--------------------------------

### Initialize MemoFS in a project

Source: https://docs.memofs.dev/introduction

Install the CLI tool and initialize the .memofs/ directory using common package managers.

```sh
npm install -D @memofs/cli
npx memofs init
```

```sh
pnpm add -D @memofs/cli
pnpm memofs init
```

```sh
bun add -d @memofs/cli
bunx memofs init
```

--------------------------------

### Install Voyage AI Adapter

Source: https://docs.memofs.dev/packages/adapters/voyage

Commands to install the adapter using various package managers.

```sh
npm install @memofs/adapter-voyage
```

```sh
pnpm add @memofs/adapter-voyage
```

```sh
yarn add @memofs/adapter-voyage
```

```sh
bun add @memofs/adapter-voyage
```

```sh
deno add npm:@memofs/adapter-voyage
```

--------------------------------

### memofs agent start

Source: https://docs.memofs.dev/packages/cli/agent

Starts an AgentFS-style workspace for a coding agent with a specified task.

```APIDOC
## memofs agent start

### Description
Starts an AgentFS-style workspace for Codex, Claude Code, or another coding agent.

### Parameters
- **--task** (string) - Required - Agent task or brief.
- **--project** (string) - Optional - Project ID.
- **--actor** (string) - Optional - Actor ID.
- **--session** (string) - Optional - Explicit safe session ID.
```

--------------------------------

### Install Semantic Search Adapter

Source: https://docs.memofs.dev/learn/cookbooks/a-claude-code

Install the transformers adapter to enable local embeddings-based search.

```bash
npm i -D @memofs/adapter-transformers
```

--------------------------------

### Start an Agent Session

Source: https://docs.memofs.dev/packages/cli/agent

Initializes an AgentFS-style workspace for a specific coding task.

```bash
memofs agent start --task "Implement OAuth2 login flow"
```

--------------------------------

### Initialize and Generate Agent Configuration

Source: https://docs.memofs.dev/blog/the-memory-layer-for-any-ai-agent

Commands to install the MemoFS CLI, initialize a project, and generate configuration for a specific agent.

```bash
npm i -g @memofs/cli    # or: npx @memofs/cli ...
memofs init             # creates .memofs/ in your project
memofs generate agent claude --project-name "My App"
```

--------------------------------

### Install @memofs/json-rpc

Source: https://docs.memofs.dev/packages/json-rpc

Installation commands for various package managers. Requires Node.js version 22 or higher.

```sh
npm install @memofs/json-rpc
```

```sh
pnpm add @memofs/json-rpc
```

```sh
yarn add @memofs/json-rpc
```

```sh
bun add @memofs/json-rpc
```

--------------------------------

### Install @memofs/testing

Source: https://docs.memofs.dev/packages/testing

Commands to install the testing utilities as a development dependency using various package managers.

```sh
npm install -D @memofs/testing
```

```sh
pnpm add -D @memofs/testing
```

```sh
yarn add -D @memofs/testing
```

```sh
bun add -d @memofs/testing
```

--------------------------------

### MemoFS status output example

Source: https://docs.memofs.dev/packages/cli/memory

Example of the console output generated by the memofs status command.

```text
# MemoFS Status
Root: /path/to/project

## Store Health
- Core memory: present
- Notes memory: present
- Total events: 42

## Compliance (session started at 2026-07-13T12:00:00Z)
- ✓ Context loaded at session start
- ✓ Memory consulted during session
- ✓ Facts persisted
```

--------------------------------

### Define Workspace Connectors Configuration

Source: https://docs.memofs.dev/packages/connectors

Example structure for the connectors.json configuration file.

```json
{
  "connectors": [
    {
      "id": "github-main",
      "type": "github",
      "enabled": true,
      "schedule": "@hourly",
      "sourceMapping": { "repository": "owner/repo", "kinds": ["issues", "prs", "discussions"] },
      "secretRef": "ss_abc123"
    }
  ]
}
```

--------------------------------

### Install Workers AI Adapter

Source: https://docs.memofs.dev/packages/adapters/workers-ai

Commands to install the adapter using various package managers.

```sh
npm install @memofs/adapter-workers-ai
```

```sh
pnpm add @memofs/adapter-workers-ai
```

```sh
yarn add @memofs/adapter-workers-ai
```

```sh
bun add @memofs/adapter-workers-ai
```

```sh
deno add npm:@memofs/adapter-workers-ai
```

--------------------------------

### Start Aider session

Source: https://docs.memofs.dev/learn/cookbooks/c-aider

Launch Aider to begin a session with the configured memory file loaded as context.

```bash
aider
```

--------------------------------

### Generate Gemini setup files

Source: https://docs.memofs.dev/learn/cookbooks/b-gemini

Generates the necessary rules and MCP configuration files for Gemini integration.

```bash
npx @memofs/cli generate agent gemini --project-name "Your project name"
```

--------------------------------

### Workspace Configuration File

Source: https://docs.memofs.dev/packages/core/configuration

Example of a .memofs/config.json file for defining team-wide project settings.

```json
{
  "$schema": "./node_modules/@memofs/cli/schema/config.json",
  "runtime": "local",
  "projectId": "project-abc",
  "recall": {
    "engine": "hybrid",
    "embeddingModel": "openai/text-embedding-3-small"
  },
  "cloud": {
    "baseUrl": "https://memofs.dev/api/v1"
  }
}
```

--------------------------------

### Integrate MemoFS with Vercel AI SDK

Source: https://docs.memofs.dev/packages/adapters/ai-sdk

Example showing how to build runtime instructions and memory tools for use with generateText.

```ts
import { MemoFS } from "@memofs/core";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";
import {
  createAiSdkRuntimeFromMemoFS,
  buildRuntimeMemoryToolDefinition,
  buildAgentSessionInstructions,
} from "@memofs/adapter-ai-sdk";

const memo = new MemoFS({ /* config */ });

// 1. Build runtime context instructions
const instructions = buildAgentSessionInstructions({
  projectName: "my-app",
});

// 2. Generate Vercel AI SDK compatible tools
const memoryTool = buildRuntimeMemoryToolDefinition({
  memo,
  name: "project_memory",
  description: "Search and update project memories",
});

// 3. Execute generation
const response = await generateText({
  model: openai("gpt-4o"),
  system: `You are an AI assistant. Context:
${instructions}`,
  tools: {
    memory: memoryTool,
  },
  prompt: "What were our decisions about database routing?",
});

console.log(response.text);
```

--------------------------------

### Conventional Commit Examples

Source: https://docs.memofs.dev/community/contributing

Examples of commit messages following the Conventional Commits specification.

```text
feat(core): add memory compaction
fix(cli): handle missing config gracefully
docs: update API reference
```

--------------------------------

### Enable Corepack

Source: https://docs.memofs.dev/community/contributing

Required setup to manage pnpm versions using Corepack.

```bash
corepack enable
corepack prepare pnpm@9 --activate
```

--------------------------------

### Initialize R2 Store Client

Source: https://docs.memofs.dev/packages/adapters/r2

Example of binding an R2 bucket to the Worker environment and initializing the MemoFS store client.

```ts
import { MemoFS } from "@memofs/core";
import { createR2BlobClient } from "@memofs/adapter-r2";

export default {
  async fetch(request, env) {
    const memo = new MemoFS({
      projectId: "r2-project",
      // Bind to Cloudflare R2 Bucket
      store: createR2BlobClient({
        bucket: env.MY_R2_BUCKET,
      }),
    });
    
    // ... handling fetch ...
  }
}
```

--------------------------------

### Secure the server with a token

Source: https://docs.memofs.dev/packages/server/node

Start the server with authentication enabled by providing a bearer token.

```bash
MEMOFS_SERVER_TOKEN="your-secret" memofs-server
```

--------------------------------

### Run CLI on demand

Source: https://docs.memofs.dev/packages/cli

Execute the CLI without a permanent installation.

```bash
npx memofs --help
```

--------------------------------

### Install MemoFS CLI

Source: https://docs.memofs.dev/

Install the MemoFS CLI as a development dependency using your preferred package manager. Requires Node.js version 22 or higher.

```bash
npm install -D @memofs/cli
```

```bash
pnpm add -D @memofs/cli
```

```bash
yarn add -D @memofs/cli
```

```bash
bun add -d @memofs/cli
```

```bash
deno add -D npm:@memofs/cli
```

--------------------------------

### Implement context injection hook

Source: https://docs.memofs.dev/learn/cookbooks/b-command-code

Script to inject project context at the start of a session.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Replace the line below with whatever memofs CLI command prints current
# project context as plain text — check the Memory Commands reference
# (docs.memofs.dev/packages/cli/memory) for the exact invocation, since
# this cookbook hasn't been verified against that specific command yet.
CONTEXT=$(npx @memofs/cli context 2>/dev/null || echo "memofs: no context available")

jq -n --arg ctx "$CONTEXT" '{
  hookSpecificOutput: {
    hookEventName: "SessionStart",
    additionalContext: $ctx
  }
}'
```

--------------------------------

### MemoFS Client Convenience Methods

Source: https://docs.memofs.dev/packages/core/agentfs

Using the MemoFS client to start, write, extract, and complete sessions directly.

```typescript
const session = await memo.agentfs.startSession({
  task: "implement authentication flow",
});

await memo.agentfs.writeFile({
  sessionId: session.sessionId,
  path: "plan.md",
  content: "# Auth Plan",
});

const extracted = await memo.agentfs.extract({
  sessionId: session.sessionId,
});

await memo.agentfs.complete({
  sessionId: session.sessionId,
  extractDurableMemory: true,
});
```

--------------------------------

### Compare Embedder Latency

Source: https://docs.memofs.dev/packages/benchmark-kit

Full example comparing OpenAI and Voyage AI embedders using the benchmark kit.

```ts
import { BenchmarkSuite, BenchmarkRunner, MarkdownReporter } from "@memofs/benchmark-kit";
import { createEmbedderWorkloads } from "@memofs/benchmark-kit/workloads";
import { createOpenAIEmbedder } from "@memofs/adapter-openai";
import { createVoyageEmbedder } from "@memofs/adapter-voyage";

// 1. Initialize targets
const targets = {
  openai: createOpenAIEmbedder({ model: "text-embedding-3-small" }),
  voyage: createVoyageEmbedder({ model: "voyage-3" }),
};

// 2. Build suite
const suite = new BenchmarkSuite("embedder-comparison");
for (const [name, embedder] of Object.entries(targets)) {
  suite.benchmark(name, createEmbedderWorkloads(embedder));
}

// 3. Run and Report
const runner = new BenchmarkRunner();
const results = await runner.runSuite(suite);

await MarkdownReporter.report(results, {
  outputPath: "./benchmarks/embedder-results.md",
});
```

--------------------------------

### Initialize MemoFS

Source: https://docs.memofs.dev/

Set up the project directory with the necessary memory, notes, and index files.

```bash
npx memofs init
```

--------------------------------

### Manage Agent Session Lifecycle

Source: https://docs.memofs.dev/packages/core/client/agentfs

Demonstrates starting a session, writing a file, extracting memory, and completing the session with durable memory enabled.

```typescript
const session = await memo.agentfs.startSession({
  task: "implement auth flow",
});

await memo.agentfs.writeFile({
  sessionId: session.sessionId,
  path: "plan.md",
  content: "# Auth Plan",
});

const extracted = await memo.agentfs.extract({ sessionId: session.sessionId });
const completed = await memo.agentfs.complete({
  sessionId: session.sessionId,
  extractDurableMemory: true,
});

console.log(completed.durableMemoryWritten);
```

--------------------------------

### Initialize and use MemoFS SDK

Source: https://docs.memofs.dev/blog/the-memory-layer-for-any-ai-agent

Demonstrates initializing the MemoFS runtime and performing basic operations like recording notes, recalling information, and generating context.

```typescript
import { MemoFS } from "@memofs/core";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

const memo = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "my-agent",
  mode: "local",
});
await memo.bootstrap();

// Persist a durable fact — passes the write gate (secret filter + durability classify)
await memo.notes.record({ content: "Use D1 for tenant metadata.", kind: "decision" });

// Recall for a task — hybrid retrieval, works offline, no API keys
const hits = await memo.recall("database decisions");

// Or get a packed, task-ready briefing to drop into your prompt
const context = await memo.context({ query: "fix the auth bug", taskType: "debug" });
```

--------------------------------

### Initialize CLI Configuration

Source: https://docs.memofs.dev/packages/cli/config

Creates a .memofs/config.json file without storing sensitive credentials.

```bash
memofs config init --runtime hybrid --cloud-url https://memofs.dev/api/v1
```

--------------------------------

### createMemoFSMcpRuntimeFromConfig

Source: https://docs.memofs.dev/api/mcp-server

Builds a MemoFS client from configuration and wraps it as a MemoFSMcpRuntime.

```APIDOC
## createMemoFSMcpRuntimeFromConfig

### Description
Builds a MemoFS client from configuration and wraps it as a MemoFSMcpRuntime. This is the primary entry point for initializing the runtime.

### Signature
`function createMemoFSMcpRuntimeFromConfig(options?: RuntimeFactoryOptions): MemoFSMcpRuntime;`
```

--------------------------------

### Initialize project memory and rules

Source: https://docs.memofs.dev/learn/cookbooks/b-command-code

Commands to initialize project memory and generate agent rules from scratch.

```bash
cd /path/to/your/project
npx @memofs/cli init
```

```bash
npx @memofs/cli generate agent-rules agents --project-name "Your project name"
```

--------------------------------

### Recall JSON-RPC Response

Source: https://docs.memofs.dev/packages/server/http-api

Example of a successful response from the recall method.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "items": [
      {
        "content": "Database migrations run via Drizzle Migrator.",
        "score": 0.89,
        "source": { "kind": "notes", "path": "memory/notes.md" }
      }
    ]
  }
}
```

--------------------------------

### createHostedRuntime

Source: https://docs.memofs.dev/api/server

Assembles a unified MemoFS client using an injected storage and optional intelligence adapters.

```APIDOC
## createHostedRuntime

### Description
Assembles a unified MemoFS client using an injected storage and optional intelligence adapters.

### Signature
`function createHostedRuntime(options: HostedRuntimeOptions): MemoFS;`
```

--------------------------------

### Recall JSON-RPC Request

Source: https://docs.memofs.dev/packages/server/http-api

Example of a POST request to the recall method.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "recall",
  "params": {
    "query": "how to deploy database",
    "limit": 3
  }
}
```

--------------------------------

### GET /health

Source: https://docs.memofs.dev/packages/server/node

Performs a health check on the running memofs-server instance.

```APIDOC
## GET /health

### Description
Returns the health status, server name, and version of the running memofs-server instance.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the server is healthy
- **name** (string) - The name of the server
- **version** (string) - The version of the server

#### Response Example
{
  "ok": true,
  "name": "memofs-server",
  "version": "0.1.0"
}
```

--------------------------------

### Initialize and generate Codex configuration

Source: https://docs.memofs.dev/learn/cookbooks/b-command-code

Use these commands to set up a project and generate a Codex configuration for Command Code.

```bash
cd /path/to/your/project
npx @memofs/cli init
npx @memofs/cli generate agent codex --scope local
```

--------------------------------

### GET /health

Source: https://docs.memofs.dev/packages/server/http-api

Performs a liveness probe to check the status of the service.

```APIDOC
## GET /health

### Description
Performs a liveness probe to check the status of the service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the service is healthy.
```

--------------------------------

### Create a hosted runtime

Source: https://docs.memofs.dev/api/server

Assembles a unified MemoFS client using injected storage and optional intelligence adapters.

```typescript
function createHostedRuntime(options: HostedRuntimeOptions): MemoFS;
```

--------------------------------

### memo.agentfs.startSession

Source: https://docs.memofs.dev/packages/core/client/agentfs

Initializes a new agent session for a specific task.

```APIDOC
## memo.agentfs.startSession

### Description
Starts a new agent session to track tasks and file operations.

### Parameters
- **task** (string) - Required - The description of the task to be performed by the agent.

### Returns
- **sessionId** (string) - The unique identifier for the created session.
```

--------------------------------

### List configured connectors

Source: https://docs.memofs.dev/packages/cli/connectors

Displays all connectors currently defined in connectors.json.

```bash
memofs connectors list
```

--------------------------------

### Initialize BenchmarkSuite

Source: https://docs.memofs.dev/packages/benchmark-kit

Create a new benchmark suite and configure iteration counts.

```ts
import { BenchmarkSuite } from "@memofs/benchmark-kit";

const suite = new BenchmarkSuite("embedder-benchmarks")
  .setIterations(5);
```

--------------------------------

### Configure kilo.jsonc instructions

Source: https://docs.memofs.dev/learn/cookbooks/b-kilo-code

Add the generated rules file to the instructions array in kilo.jsonc.

```jsonc
{
  "instructions": ["AGENTS.md"]
}
```

--------------------------------

### GET {cloudBaseUrl}/projects/:projectId/connectors/secret

Source: https://docs.memofs.dev/packages/connectors

Fetches a decrypted token from the MemoFS cloud API using a secret reference.

```APIDOC
## GET {cloudBaseUrl}/projects/:projectId/connectors/secret

### Description
Fetches decrypted tokens from the MemoFS cloud API.

### Method
GET

### Endpoint
{cloudBaseUrl}/projects/:projectId/connectors/secret?ref=:secretRef

### Parameters
#### Path Parameters
- **projectId** (string) - Required - The project identifier.

#### Query Parameters
- **ref** (string) - Required - The secret reference identifier.

### Authentication
- Bearer API key
```

--------------------------------

### Configure opencode MCP server

Source: https://docs.memofs.dev/packages/mcp/index

Manual configuration for opencode.

```jsonc
// Project: ./opencode.json (or .jsonc)
// Global:  ~/.config/opencode/opencode.json (add "--root", "/absolute/path/to/project")
{
  "mcp": {
    "memofs": {
      "type": "local",
      "command": ["npx", "-y", "@memofs/mcp-server"],
      "enabled": true
    }
  }
}
```

--------------------------------

### Install MCP Server Dependency

Source: https://docs.memofs.dev/packages/mcp

Commands to add the MCP server as a project dependency using various package managers.

```sh
npm install @memofs/mcp-server
```

```sh
pnpm add @memofs/mcp-server
```

```sh
yarn add @memofs/mcp-server
```

```sh
bun add @memofs/mcp-server
```

```sh
deno install npm:@memofs/mcp-server
```

--------------------------------

### Run Embedder Contract Tests

Source: https://docs.memofs.dev/packages/testing

Example of using embedderContractTests within a Vitest suite to validate a custom embedder implementation.

```ts
import { describe } from "vitest";
import { embedderContractTests } from "@memofs/testing/contracts";
import { createCustomEmbedder } from "./my-embedder";

describe("Custom Embedder Contract Compliance", () => {
  embedderContractTests(() => createCustomEmbedder({
    apiKey: "test-key",
  }));
});
```

--------------------------------

### Initialize MemoFS Project Memory

Source: https://docs.memofs.dev/learn/cookbooks/a-claude-code

Run these commands from the project root to initialize the local memory engine and generate a project ID.

```bash
cd /path/to/your/project
npx @memofs/cli init
```

--------------------------------

### Initialize Workers AI Extractor

Source: https://docs.memofs.dev/packages/adapters/workers-ai

Example of initializing the MemoFS instance with the Workers AI extractor within a Cloudflare Worker.

```ts
import { MemoFS } from "@memofs/core";
import { createWorkersAiExtractor } from "@memofs/adapter-workers-ai";
import { createR2BlobClient } from "@memofs/adapter-r2";

export default {
  async fetch(request, env) {
    const memo = new MemoFS({
      store: createR2BlobClient({ bucket: env.BUCKET }),
      projectId: "worker-ai-project",
      extractor: createWorkersAiExtractor({
        ai: env.AI, // Injected Cloudflare Workers AI binding
        model: "@cf/meta/llama-3-8b-instruct", // Optional override
      }),
    });
    
    // ... handling fetch ...
  }
}
```

--------------------------------

### Initialize MemoFS with Turso

Source: https://docs.memofs.dev/packages/adapters/turso

Configure MemoFS to use the Turso metadata store for index recall storage.

```ts
import { MemoFS } from "@memofs/core";
import { createTursoMetadataStore } from "@memofs/adapter-turso";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

const memo = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "turso-project",
  
  // Inject Turso/libSQL for metadata tracking
  recallStore: createTursoMetadataStore({
    url: process.env.TURSO_DATABASE_URL,
    authToken: process.env.TURSO_AUTH_TOKEN,
  }),
});
```

--------------------------------

### MemoFS Constructor

Source: https://docs.memofs.dev/packages/core/client

Instantiates a new MemoFS client instance with the provided configuration.

```APIDOC
## Constructor

### Description
Instantiates a new unified client for memory operations.

### Signature
`new MemoFS(config?: MemoFsConfig)`

### Configuration Options (MemoFsConfig)
- **store** (MemoryStore) - Required - Memory store adapter (filesystem or in-memory).
- **mode** (MemoFSRuntimeMode) - Optional - Runtime mode: "local" | "hybrid". Default: "local".
- **projectId** (string) - Optional - Unique identifier for the project workspace.
- **cloud** (MemoFsCloudOptions) - Optional - Cloud client config (baseUrl, apiKey) for hybrid sync.
- **embedder** (MemoryEmbedder) - Optional - Vector embedding client.
- **reranker** (Reranker) - Optional - Hybrid search results reranker.
- **extractor** (Extractor) - Optional - Entity/relationship graph extractor.
- **llmClient** (LlmClient) - Optional - Provider-neutral LLM client.
```

--------------------------------

### Register MemoFS MCP server via CLI

Source: https://docs.memofs.dev/learn/cookbooks/b-kilo-code

Use the interactive wizard to add the MCP server.

```bash
kilo mcp add memofs
```

--------------------------------

### Initialize MemoFS client

Source: https://docs.memofs.dev/api/core

Instantiate the MemoFS client using a configuration object.

```typescript
const memo = new MemoFS(config);
```

--------------------------------

### Initialize MemoFS in Hybrid Mode

Source: https://docs.memofs.dev/

Configures MemoFS to use local storage for speed while synchronizing replicas to the cloud.

```typescript
import { MemoFS } from "@memofs/core"
import { createNodeFsStore } from "@memofs/core/node-fs"

// Local speed + cloud replica.
const memo = new MemoFS({
  store: createNodeFsStore(
    { rootDir: "." }
  ),
  mode: "hybrid",
  cloud: {
    baseUrl: process.env.MEMOFS_CLOUD_URL,
    apiKey: process.env.MEMOFS_API_KEY,
  },
})
```

--------------------------------

### Initialize Hosted Runtime

Source: https://docs.memofs.dev/packages/server

Configures a MemoFS runtime instance with a required memory store and optional intelligence providers.

```ts
import { createHostedRuntime } from "@memofs/server";
import { InMemoryMemoryStore } from "@memofs/core";

const runtime = createHostedRuntime({
  // The only required slot: the memory store (your file replica).
  store: new InMemoryMemoryStore(),
  projectId: "my-project",

  // Optional intelligence slots — each runs its deterministic default
  // when omitted. Inject a provider adapter to upgrade a slot.
  // embedder: yourEmbedder,
  // reranker: yourReranker,
  // extractor: yourExtractor,
  // llmClient: yourLlmClient,
});

await runtime.writeMemory({ content: "self-hosted runtime runs the engine" });
const hits = await runtime.recall("self-hosted");
```

--------------------------------

### buildAgentSessionInstructions

Source: https://docs.memofs.dev/packages/adapters/ai-sdk

Generates system-prompt instructions for an AI agent to manage core and archival memory.

```APIDOC
## buildAgentSessionInstructions

### Description
Generates the system-prompt instructions prompting the agent on how to use and structure core/archival memory.

### Parameters
- **projectName** (string) - Required - The name of the project to generate instructions for.
```

--------------------------------

### Generate Agent Configurations

Source: https://docs.memofs.dev/packages/cli/generate

Commands to initialize agent-specific rules, hooks, and MCP server configurations.

```bash
memofs generate agent claude --project-name "My App"
memofs generate agent codex --scope local
memofs generate agent cursor          # rules + MCP only (no usable hooks)
memofs generate agent --list
```

--------------------------------

### Manual MCP Configuration for AI Clients

Source: https://docs.memofs.dev/packages/mcp

Manual configuration snippets for various AI clients. Note that global configurations often require an absolute --root path.

```json
// Project: ./.mcp.json (committable — no --root needed)
// Global:  ~/.claude.json (add "--root", "/absolute/path/to/project" to args)
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

```json
// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
// Desktop has no project cwd, so --root is required.
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": [
        "-y",
        "@memofs/mcp-server",
        "--root",
        "/absolute/path/to/your/project"
      ]
    }
  }
}
```

```toml
# Project: ./.codex/config.toml (drop the --root args)
# Global (Codex convention): ~/.codex/config.toml (add --root)
[mcp_servers.memofs]
command = "npx"
args = ["-y", "@memofs/mcp-server", "--root", "/absolute/path/to/your/project"]
```

```json
// Project: ./.cursor/mcp.json
// Global:  ~/.cursor/mcp.json (add "--root", "/absolute/path/to/project")
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

```jsonc
// Project: ./opencode.json (or .jsonc)
// Global:  ~/.config/opencode/opencode.json (add "--root", "/absolute/path/to/project")
{
  "mcp": {
    "memofs": {
      "type": "local",
      "command": ["npx", "-y", "@memofs/mcp-server"],
      "enabled": true
    }
  }
}
```

```json
// Project: ./.gemini/settings.json
// Global:  ~/.gemini/settings.json (add "--root", "/absolute/path/to/project")
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

```json
// Project: ./.vscode/mcp.json
{
  "servers": {
    "memofs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

--------------------------------

### runConnectors(options)

Source: https://docs.memofs.dev/packages/connectors

Runs all enabled connectors defined in the .memofs/connectors.json file.

```APIDOC
## runConnectors(options)

### Description
Runs all enabled connectors in `.memofs/connectors.json`. Returns a `RunConnectorsResult` containing aggregated results of the execution.

### Parameters
- **rootDir** (string) - Required - The .memofs/ parent directory
- **memo** (MemoFS) - Required - The host's MemoFS instance (single-writer)
- **secretResolver** (SecretResolver) - Required - Resolves secretRef to token at runtime
- **connectorRegistry** (ConnectorRegistry) - Optional - Custom registry (defaults to built-ins)
- **onlyType** (string) - Optional - Run only connectors of this type
- **signal** (AbortSignal) - Optional - Abort signal for cancellation

### Returns
- **RunConnectorsResult** (object) - { written, skipped, errors, ran }
```

--------------------------------

### Verify MCP Tools

Source: https://docs.memofs.dev/learn/cookbooks/c-amazon-q

Execute this command within a Q CLI session to confirm that the MemoFS tools are correctly registered.

```text
/tools
```

--------------------------------

### memofs init

Source: https://docs.memofs.dev/packages/cli/memory

Initializes a new MemoFS memory workspace by generating the canonical .memofs/ structure.

```APIDOC
## memofs init

### Description
Initializes a new MemoFS memory workspace, generating the canonical .memofs/ structure (11 files across memory/, events/, indexes/, graph/, and snapshots/).

### Options
- **-f, --force** (boolean) - Optional - Overwrite existing seed files (Default: false)
- **-p, --project-id** (string) - Optional - Explicit project ID
- **--no-input** (boolean) - Optional - Skip interactive prompts (Default: false)
```

--------------------------------

### createR2BlobClient(config: R2BlobClientConfig)

Source: https://docs.memofs.dev/packages/adapters/r2

Initializes the R2 blob client to be used with the MemoFS constructor.

```APIDOC
## createR2BlobClient

### Description
Initializes a new R2 blob client instance for use with MemoFS, allowing the system to store data in a Cloudflare R2 bucket.

### Parameters
#### Configuration Object (R2BlobClientConfig)
- **bucket** (R2Bucket) - Required - The Cloudflare R2 bucket binding object.
- **prefix** (string) - Optional - Optional key prefix to isolate multiple projects in one bucket.
- **contentType** (string) - Optional - Default content-type header for written blobs (default: text/plain).

### Usage Example
```typescript
import { MemoFS } from "@memofs/core";
import { createR2BlobClient } from "@memofs/adapter-r2";

const memo = new MemoFS({
  projectId: "r2-project",
  store: createR2BlobClient({
    bucket: env.MY_R2_BUCKET,
    prefix: "my-app/",
    contentType: "application/octet-stream"
  }),
});
```
```

--------------------------------

### Import MemoFS Client

Source: https://docs.memofs.dev/packages/core/client

Import the MemoFS class from the core package to begin using the client.

```typescript
import { MemoFS } from "@memofs/core";
```

--------------------------------

### Generate agent rules

Source: https://docs.memofs.dev/packages/cli/generate

Create platform-specific instruction files for AI agents to enable MemoFS tool usage.

```bash
memofs generate agent-rules claude --project-name "My App"
memofs generate agent-rules --list
```

--------------------------------

### Push local file replicas

Source: https://docs.memofs.dev/packages/cli/cloud

Uploads local .memofs/ file replicas to the cloud, optionally specifying a base cursor for the sync.

```bash
memofs cloud sync push
memofs cloud sync push --base-cursor <cursor>
```

--------------------------------

### Run Custom Connectors

Source: https://docs.memofs.dev/packages/connectors

Executes connectors using a custom registry instance.

```javascript
await runConnectors({ rootDir, memo, secretResolver, connectorRegistry: registry });
```

--------------------------------

### Generate Copilot configuration

Source: https://docs.memofs.dev/learn/cookbooks/b-copilot

Creates the necessary instruction files and MCP server configuration for Copilot integration.

```bash
npx @memofs/cli generate agent copilot --project-name "Your project name"
```

--------------------------------

### Configure Claude MCP server

Source: https://docs.memofs.dev/packages/mcp/index

Manual configuration for Claude Code and Claude Desktop.

```json
// Project: ./.mcp.json (committable — no --root needed)
// Global:  ~/.claude.json (add "--root", "/absolute/path/to/project" to args)
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

```json
// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
// Desktop has no project cwd, so --root is required.
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": [
        "-y",
        "@memofs/mcp-server",
        "--root",
        "/absolute/path/to/your/project"
      ]
    }
  }
}
```

--------------------------------

### Compose a MemoFS MCP server

Source: https://docs.memofs.dev/api/mcp-server

Demonstrates the standard composition of a runtime, protocol server, and stdio transport.

```typescript
import {
  createMemoFSMcpRuntimeFromConfig,
  createMemoFSMcpProtocolServer,
  runStdioServer,
} from "@memofs/mcp-server";

// 1. A runtime adapter wraps a MemoFS client — build one from config...
const runtime = createMemoFSMcpRuntimeFromConfig({ rootDir: "." });
// ...or from an existing MemoFS instance: createMemoFSMcpRuntimeFromMemoFS(memo)

// 2. The protocol server handles JSON-RPC messages against that runtime.
const server = createMemoFSMcpProtocolServer({ runtime });

// 3. A transport drives it. The stdio transport reads stdin/writes stdout
//    until the stream closes.
await runStdioServer(server);
```

--------------------------------

### Initialize MemoFS Workspace

Source: https://docs.memofs.dev/packages/cli/memory

Initializes a new memory workspace with the required directory structure.

```bash
memofs init
```

--------------------------------

### createTursoMetadataStore

Source: https://docs.memofs.dev/packages/adapters/turso

Initializes a new Turso metadata store for use with MemoFS, requiring a database URL and optional authentication and table configuration.

```APIDOC
## createTursoMetadataStore(config: TursoMetadataStoreConfig)

### Description
Creates a metadata store instance using Turso or libSQL to handle index recall storage within a MemoFS project.

### Parameters
#### Configuration Object (TursoMetadataStoreConfig)
- **url** (string) - Required - Database endpoint URL (supports libsql://, https://, file:).
- **authToken** (string) - Optional - Authentication token for remote Turso databases.
- **tableName** (string) - Optional - Database table name to use (default: "memofs_metadata").

### Usage Example
```typescript
import { createTursoMetadataStore } from "@memofs/adapter-turso";

const recallStore = createTursoMetadataStore({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
  tableName: "custom_metadata_table"
});
```
```

--------------------------------

### Initialize registry with createConnectorRegistry

Source: https://docs.memofs.dev/api/connectors

Creates a registry seeded with built-in GitHub and Notion connectors, plus optional additional connectors.

```typescript
function createConnectorRegistry(extras?: readonly Connector[]): ConnectorRegistry;
```

--------------------------------

### Configure Hybrid Storage with R2 and Turso

Source: https://docs.memofs.dev/configure/storage

Initializes a MemoFS instance in hybrid mode by injecting specific adapters for blob storage and metadata indexing.

```typescript
import { MemoFS } from "@memofs/core";
import { createR2BlobClient } from "@memofs/adapter-r2";
import { createTursoMetadataStore } from "@memofs/adapter-turso";

const memo = new MemoFS({
  projectId: "prod-workspace",
  mode: "hybrid",
  
  // Inject R2 for raw storage
  store: createR2BlobClient({
    bucket: process.env.R2_BUCKET_NAME,
    accountId: process.env.CF_ACCOUNT_ID,
  }),
  
  // Inject Turso for fast graph queries
  recallStore: createTursoMetadataStore({
    url: process.env.TURSO_DB_URL,
    authToken: process.env.TURSO_DB_TOKEN,
  }),
});
```

--------------------------------

### Execute BenchmarkRunner

Source: https://docs.memofs.dev/packages/benchmark-kit

Configure and run a benchmark suite using the runner.

```ts
import { BenchmarkRunner } from "@memofs/benchmark-kit";

const runner = new BenchmarkRunner({
  warmupIterations: 1,
  timeout: 60000,
});
const results = await runner.runSuite(suite);
```

--------------------------------

### Configure Gemini CLI MCP server

Source: https://docs.memofs.dev/packages/mcp/index

Manual configuration for Gemini CLI.

```json
// Project: ./.gemini/settings.json
// Global:  ~/.gemini/settings.json (add "--root", "/absolute/path/to/project")
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

--------------------------------

### Configure Memofs MCP Server

Source: https://docs.memofs.dev/packages/mcp/hosted-mcp-endpoint

Add this configuration to your .cursor/mcp.json file to enable the Memofs MCP server. Ensure you replace the placeholder values with your actual project ID and API key.

```json
// Save as `.cursor/mcp.json` in your project (or merge into the global one)
{
  "mcpServers": {
    "memofs": {
      "url": "https://memofs.dev/api/v1/projects/<project-id>/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```

--------------------------------

### Configure Cursor MCP server

Source: https://docs.memofs.dev/packages/mcp/index

Manual configuration for Cursor.

```json
// Project: ./.cursor/mcp.json
// Global:  ~/.cursor/mcp.json (add "--root", "/absolute/path/to/project")
{
  "mcpServers": {
    "memofs": {
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"]
    }
  }
}
```

--------------------------------

### runStdioServer

Source: https://docs.memofs.dev/api/mcp-server

Runs a protocol server over stdio.

```APIDOC
## runStdioServer

### Description
Runs a protocol server over stdio, reading newline-delimited JSON-RPC from stdin and writing responses to stdout. It resolves when stdin closes.

### Signature
`function runStdioServer(server: MemoFSMcpProtocolServer): Promise<void>;`
```

--------------------------------

### Create memory snapshot

Source: https://docs.memofs.dev/packages/cli/memory

Generates a snapshot bundle in the snapshots directory with a custom label.

```bash
memofs snapshot --label "before-refactor"
```

--------------------------------

### Configure Command Code session hooks

Source: https://docs.memofs.dev/learn/cookbooks/b-command-code

Settings for SessionStart and Stop hooks in .commandcode/settings.json.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "./.commandcode/hooks/memofs-context.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "./.commandcode/hooks/memofs-summary.sh" }
        ]
      }
    ]
  }
}
```

--------------------------------

### Initialize OpenAI Embedder

Source: https://docs.memofs.dev/packages/adapters/openai

Instantiate the MemoFS client with the OpenAI embedder configuration.

```ts
import { MemoFS } from "@memofs/core";
import { createOpenAIEmbedder } from "@memofs/adapter-openai";
import { createNodeFsMemoryStore } from "@memofs/core/node-fs";

const memo = new MemoFS({
  store: createNodeFsMemoryStore({ rootDir: "." }),
  projectId: "openai-project",
  embedder: createOpenAIEmbedder({
    apiKey: process.env.OPENAI_API_KEY,
    model: "text-embedding-3-small", // or text-embedding-3-large, text-embedding-ada-002
    dimensions: 1536, // Optional dimension configuration
  }),
});
```

--------------------------------

### Register MCP server in Zed settings

Source: https://docs.memofs.dev/learn/cookbooks/b-zed

Add this configuration to your .zed/settings.json or global settings to enable the MemoFS MCP server.

```json
{
  "context_servers": {
    "memofs": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@memofs/mcp-server"],
      "env": {}
    }
  }
}
```

--------------------------------

### createMemoFSMcpRuntimeFromConfig function signature

Source: https://docs.memofs.dev/api/mcp-server

Builds a MemoFS client from configuration options.

```typescript
function createMemoFSMcpRuntimeFromConfig(
  options?: RuntimeFactoryOptions
): MemoFSMcpRuntime;
```

--------------------------------

### Generate Claude Agent Configurations

Source: https://docs.memofs.dev/learn/cookbooks/a-claude-code

Creates the necessary rules, settings, and MCP server configuration files to integrate MemoFS with Claude.

```bash
npx @memofs/cli generate agent claude --project-name "Your project name"
```
Tokens:
Raw