Build a Custom Memory Tool

1
{
2
  "name": "memory",
3
  "input": {
4
    "command": "view",
5
    "path": "/memories/customer_service_guidelines.xml"
6
  }
7
}

1
.memory/
2
├── core.md               # Core memory, injected every turn
3
├── notes.md              # Archival memory, timestamped notes
4
└── conversations.jsonl   # Recall memory, full turn history (JSONL)

1
pnpm add ai just-bash zod

1
import { tool } from 'ai';
2
import { z } from 'zod';
3

4
const memoryInputSchema = z.object({
5
  command: z
6
    .enum(['view', 'create', 'update', 'search'])
7
    .describe(
8
      'Memory action: view to read, create to write new content, update to change existing content, search to find relevant lines.',
9
    ),
10
  path: z
11
    .string()
12
    .optional()
13
    .describe(
14
      'Memory path under /memories, such as /memories/core.md or /memories/notes.md. Required for view, create, and update.',
15
    ),
16
  content: z
17
    .string()
18
    .optional()
19
    .describe('Text to write for create or update commands.'),
20
  mode: z
21
    .enum(['append', 'overwrite'])
22
    .optional()
23
    .describe(
24
      'Write mode for update: append adds to existing content, overwrite replaces it. Defaults to overwrite.',
25
    ),
26
  query: z
27
    .string()
28
    .optional()
29
    .describe(
30
      'Search keywords for the search command. Prefer short focused terms.',
31
    ),
32
});
33

34
const memoryTool = tool({
35
  description: `Use this tool to read and maintain long-term memory under /memories.
36

37
Rules:
38
- If the user prompt might depend on preferences, history, constraints, or goals, search first, then reply.
39
- If the prompt is fully self-contained or general knowledge, reply directly.
40
- Keep searches short and focused (1-4 words).
41
- Store durable user facts in /memories/core.md and detailed notes in /memories/notes.md.
42
- Keep memory operations invisible in user-facing replies.`,
43
  inputSchema: memoryInputSchema,
44
  execute: async input => {
45
    try {
46
      const output = await runMemoryCommand(input);
47
      return { output };
48
    } catch (error) {
49
      return { output: `Memory action failed: ${(error as Error).message}` };
50
    }
51
  },
52
});

1
import { tool } from 'ai';
2
import { Bash, ReadWriteFs } from 'just-bash';
3
import { z } from 'zod';
4

5
const fs = new ReadWriteFs({ root: process.cwd() });
6
const bash = new Bash({ fs, cwd: '/' });
7

8
const memoryTool = tool({
9
  description: `Run bash commands only for memory-related tasks.
10

11
This tool is restricted to memory workflows. Do not use it for
12
general project work, code changes, dependency management, or
13
system administration.
14

15
Inside the tool, use paths under /.memory:
16
- /.memory/core.md for key facts that should be reused later
17
- /.memory/notes.md for detailed notes
18
- /.memory/conversations.jsonl for full turn history
19

20
Rules:
21
- Only perform memory-related reads/writes and conversation recall
22
- Keep /.memory/core.md short and focused
23
- Prefer append-friendly notes in /.memory/notes.md for details
24
- If the user asks about prior conversations, search
25
  /.memory/conversations.jsonl for relevant keywords first
26
- Use >> to append, > to overwrite, and perl -pi -e for in-place edits
27

28
Examples:
29
- cat /.memory/core.md
30
- echo "- User prefers concise answers" >> /.memory/core.md
31
- perl -pi -e 's/concise answers/detailed answers/g' /.memory/core.md
32
- grep -n "project" /.memory/notes.md
33
- echo "2026-02-16: started a Rust CLI" >> /.memory/notes.md
34
- grep -niE "pricing|budget" /.memory/conversations.jsonl
35
- tail -n 40 /.memory/conversations.jsonl | jq -c '.role + ": " + .content'`,
36
  inputSchema: z.object({
37
    command: z.string().describe('The bash command to execute.'),
38
  }),
39
  execute: async ({ command }) => {
40
    const unapprovedCommand = findUnapprovedCommand(command);
41
    if (unapprovedCommand) {
42
      return {
43
        stdout: '',
44
        stderr: `Blocked unapproved command: ${unapprovedCommand}\n`,
45
        exitCode: 1,
46
      };
47
    }
48

49
    const result = await bash.exec(command);
50
    return {
51
      stdout: result.stdout,
52
      stderr: result.stderr,
53
      exitCode: result.exitCode,
54
    };
55
  },
56
});

1
import { ToolLoopAgent } from 'ai';
2

3
const today = new Date().toISOString().slice(0, 10);
4

5
const memoryAgent = new ToolLoopAgent({
6
  model: 'anthropic/claude-haiku-4.5',
7
  tools: { memory: memoryTool },
8
  prepareCall: async settings => {
9
    // user-defined function fetches the contents of /.memory/core.md on every turn
10
    const coreMemory = await readCoreMemory();
11
    return {
12
      ...settings,
13
      instructions: `Today's date is ${today}.
14

15
Core memory:
16
${coreMemory}
17

18
You can save and recall important information using the memory tool.`,
19
    };
20
  },
21
});

1
const prompt = 'Remember that my favorite editor is Neovim';
2

3
// Record the user message
4
await appendConversation({
5
  role: 'user',
6
  content: prompt,
7
  timestamp: new Date().toISOString(),
8
});
9

10
// Run the agent (loops automatically on tool calls)
11
const result = await memoryAgent.generate({ prompt });
12

13
// Record the assistant response
14
await appendConversation({
15
  role: 'assistant',
16
  content: result.text,
17
  timestamp: new Date().toISOString(),
18
});
19

20
console.log(result.text);

1
import {
2
  access,
3
  appendFile,
4
  mkdir,
5
  readFile,
6
  writeFile,
7
} from 'node:fs/promises';
8
import { join, resolve } from 'node:path';
9

10
const MEMORY_DIR = '.memory';
11
const MEMORY_ROOT = resolve(process.cwd(), MEMORY_DIR);
12
const CORE_MEMORY_PATH = join(MEMORY_ROOT, 'core.md');
13
const NOTES_PATH = join(MEMORY_ROOT, 'notes.md');
14
const CONVERSATIONS_PATH = join(MEMORY_ROOT, 'conversations.jsonl');
15

16
const DEFAULT_CORE_MEMORY = `# Core Memory
17
- Keep this short.
18
- Put stable user facts here.
19
`;
20

21
const DEFAULT_NOTES = `# Notes
22
Use this file for detailed memories and timestamped notes.
23
`;
24

25
async function ensureFile(path: string, content: string): Promise<void> {
26
  try {
27
    await access(path);
28
  } catch {
29
    await writeFile(path, content, 'utf8');
30
  }
31
}
32

33
async function ensureMemoryFilesystem(): Promise<void> {
34
  await mkdir(MEMORY_ROOT, { recursive: true });
35
  await ensureFile(CORE_MEMORY_PATH, DEFAULT_CORE_MEMORY);
36
  await ensureFile(NOTES_PATH, DEFAULT_NOTES);
37
  await ensureFile(CONVERSATIONS_PATH, '');
38
}

1
async function readCoreMemory(): Promise<string> {
2
  try {
3
    return await readFile(CORE_MEMORY_PATH, 'utf8');
4
  } catch {
5
    return '';
6
  }
7
}
8

9
async function appendConversation(entry: {
10
  role: 'user' | 'assistant';
11
  content: string;
12
  timestamp: string;
13
}): Promise<void> {
14
  await appendFile(CONVERSATIONS_PATH, `${JSON.stringify(entry)}\n`, 'utf8');
15
}

1
import { readFile, writeFile, appendFile } from 'node:fs/promises';
2
import { join, relative } from 'node:path';
3

4
const MEMORY_FILES = ['core.md', 'notes.md', 'conversations.jsonl'];
5

6
function resolveMemoryPath(path: string): string {
7
  const relativePath = path
8
    .trim()
9
    .replace(/^\/?memories\/?/, '')
10
    .replace(/^\/?\.memory\/?/, '')
11
    .replace(/^\/+/, '');
12

13
  if (!MEMORY_FILES.includes(relativePath)) {
14
    throw new Error(`Unsupported memory path: ${path}`);
15
  }
16

17
  return join(MEMORY_ROOT, relativePath);
18
}
19

20
async function runMemoryCommand(input: {
21
  command: 'view' | 'create' | 'update' | 'search';
22
  path?: string;
23
  content?: string;
24
  mode?: 'append' | 'overwrite';
25
  query?: string;
26
}): Promise<string> {
27
  const { command, path, content, mode, query } = input;
28

29
  switch (command) {
30
    case 'view': {
31
      if (!path) throw new Error('path is required for view');
32
      return await readFile(resolveMemoryPath(path), 'utf8');
33
    }
34
    case 'create':
35
    case 'update': {
36
      if (!path) throw new Error('path is required');
37
      if (!content) throw new Error('content is required');
38
      const target = resolveMemoryPath(path);
39
      if (mode === 'append') {
40
        await appendFile(target, content, 'utf8');
41
      } else {
42
        await writeFile(target, content, 'utf8');
43
      }
44
      return `${command === 'create' ? 'Created' : 'Updated'} ${path}`;
45
    }
46
    case 'search': {
47
      if (!query) throw new Error('query is required for search');
48
      const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
49
      const files = path
50
        ? [resolveMemoryPath(path)]
51
        : MEMORY_FILES.map(f => join(MEMORY_ROOT, f));
52
      const matches: string[] = [];
53

54
      for (const filePath of files) {
55
        const lines = (await readFile(filePath, 'utf8')).split('\n');
56
        for (const [i, line] of lines.entries()) {
57
          const lower = line.toLowerCase();
58
          if (terms.some(t => lower.includes(t))) {
59
            matches.push(`${relative(MEMORY_ROOT, filePath)}:${i + 1}:${line}`);
60
          }
61
        }
62
      }
63

64
      return matches.length > 0 ? matches.join('\n') : 'No matches found.';
65
    }
66
  }
67
}

1
import {
2
  type CommandNode,
3
  parse,
4
  type ScriptNode,
5
  type WordNode,
6
} from 'just-bash';
7

8
const approvedCommands = new Set([
9
  'cat',
10
  'echo',
11
  'grep',
12
  'jq',
13
  'ls',
14
  'mkdir',
15
  'perl',
16
  'sed',
17
  'tail',
18
]);
19

20
function extractLiteralWord(word: WordNode | null): string | null {
21
  if (!word || word.parts.length !== 1) return null;
22
  const [part] = word.parts;
23
  if (!part || part.type !== 'Literal') return null;
24
  return part.value;
25
}
26

27
function collectCommandNames(script: ScriptNode): string[] {
28
  const names = new Set<string>();
29

30
  const visitCommand = (command: CommandNode): void => {
31
    switch (command.type) {
32
      case 'SimpleCommand': {
33
        const name = extractLiteralWord(command.name);
34
        if (name) names.add(name);
35
        break;
36
      }
37
      case 'If': {
38
        for (const clause of command.clauses) {
39
          for (const s of clause.condition) visitStatement(s);
40
          for (const s of clause.body) visitStatement(s);
41
        }
42
        if (command.elseBody) {
43
          for (const s of command.elseBody) visitStatement(s);
44
        }
45
        break;
46
      }
47
      case 'For':
48
      case 'CStyleFor':
49
      case 'While':
50
      case 'Until':
51
      case 'Subshell':
52
      case 'Group': {
53
        for (const s of command.body) visitStatement(s);
54
        break;
55
      }
56
      case 'Case': {
57
        for (const item of command.items) {
58
          for (const s of item.body) visitStatement(s);
59
        }
60
        break;
61
      }
62
      case 'FunctionDef': {
63
        visitCommand(command.body);
64
        break;
65
      }
66
      case 'ArithmeticCommand':
67
      case 'ConditionalCommand':
68
        break;
69
    }
70
  };
71

72
  const visitStatement = (
73
    statement: ScriptNode['statements'][number],
74
  ): void => {
75
    for (const pipeline of statement.pipelines) {
76
      for (const command of pipeline.commands) {
77
        visitCommand(command);
78
      }
79
    }
80
  };
81

82
  for (const statement of script.statements) {
83
    visitStatement(statement);
84
  }
85

86
  return [...names].sort();
87
}
88

89
export function findUnapprovedCommand(commandLine: string): string | null {
90
  let script: ScriptNode;
91
  try {
92
    script = parse(commandLine);
93
  } catch {
94
    return null;
95
  }
96
  const commandNames = collectCommandNames(script);
97
  return commandNames.find(name => !approvedCommands.has(name)) ?? null;
98
}