### Install Agent Memory CLI Globally with npm

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Install the Agent Memory CLI globally using npm. Includes a workaround for potential SSL errors.

```bash
# Install the CLI globally
npm install -g myagentmemory

# If you hit SSL errors due to corporate MITM/inspection, try:
# npm config set strict-ssl false
```

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

### Install Skill Files for Agents

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Install skill files for various agents like Claude Code, Codex, Cursor, and Agent CLI.

```bash
# Install skill files for Claude Code, Codex, Cursor, and Agent
agent-memory install-skills
```

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

### Install Agent Memory CLI via npm

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Use this command to quickly install the latest agent-memory CLI on any platform. This is useful for getting the newest features as soon as they are available.

```bash
npm install -g myagentmemory
```

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

### Setup Agent Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Initializes the agent-memory environment, including creating directories and detecting necessary tools like qmd. Also includes commands for synchronization and status checks.

```bash
agent-memory init      # Create dirs, detect qmd, setup collection
agent-memory sync      # Re-index and embed all files (requires qmd)
agent-memory status    # Show config, file counts, qmd status
```

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

### qmd Auto-Setup Flow

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Details the automated setup process for qmd, including detecting its availability, checking for collections, and creating necessary collections and contexts if they don't exist. This process runs on CLI init or within the memory_search tool.

```text
  CLI init / first search
       |
       +-- detectQmd() — runs `qmd status` (5s timeout)
       |     no  --> show install instructions, stop
       |     yes --> continue
       |
       +-- checkCollection("agent-memory") — `qmd collection list --json` (10s timeout)
       |     yes --> done
       |     no  --> setupQmdCollection()
       |               |
       |               +-- qmd collection add ~/.agent-memory --name agent-memory
       |               +-- qmd context add /daily "Daily work logs" -c agent-memory
       |               +-- qmd context add /topics "Topic and event notes" -c agent-memory
       |               +-- qmd context add / "Long-term memory" -c agent-memory
       |               |
       |               +-- any step fails? log and continue (not critical)
       |
       done
```

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

### Tags and Links Example

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Demonstrates the convention for using tags and links within memory content for organization and searchability. These are indexed as regular text by qmd's BM25 search.

```markdown
  #decision [[database-choice]] Chose PostgreSQL for all backend services.
  #preference [[editor]] User prefers Neovim with LazyVim config.
  #lesson [[api-versioning]] URL prefix versioning avoids CDN cache issues.
```

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

### Add Collection and Embed for qmd

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Manually set up the collection and embed data using qmd for Agent Memory search functionality. This is an alternative to automatic setup.

```bash
qmd collection add ~/.agent-memory --name agent-memory
qmd embed
```

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

### Load Session Context

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/agent/SKILL.md

Run this at the beginning of every session to load your memory. It prints your scratchpad, today's log, long-term memory, and yesterday's log. Review it before starting work.

```bash
agent-memory context --no-search 2>/dev/null

```

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

### Install Agent Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Install the agentmemory package using npm. This is the first step to using persistent memory for your coding agents.

```bash
npm install myagentmemory
```

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

### Install Skills

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Install custom skills for Agent Memory. This command fetches and integrates additional functionalities into the agent's capabilities.

```bash
# Install skills
agent-memory install-skills
```

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

### Install Agent Memory CLI via Homebrew

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

A fast installation path for macOS users using the Homebrew package manager. This ensures agent-memory is easily managed on your system.

```bash
brew install jayzeng/agent-memory/agent-memory
```

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

### Avoid Vague Daily Log Entries

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

This example shows an ineffective daily log entry. Entries should be specific and include tags for better searchability and organization.

```bash
# Bad — too vague, no tags
agent-memory write --content "worked on auth stuff"
```

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

### Install Skills

Source: https://github.com/jayzeng/agentmemory/blob/main/CLAUDE.md

Installs the necessary skills for Claude Code and Codex to interact with the agent memory system. This script sets up the integration points for these coding agents.

```bash
# Install skills for Claude Code / Codex
bash scripts/install-skills.sh
```

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

### Fallback Read Commands

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

If qmd is not installed, these commands can be used to read long-term memory and daily logs directly.

```bash
agent-memory read --target long_term
agent-memory read --target daily
```

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

### Search Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Search the agent's memory for relevant information using semantic search. This requires the qmd package to be installed.

```javascript
const searchResults = await memory.search("python script");
```

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

### Search Memory by Keyword

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Searches the agent memory using a keyword query. This is useful for finding relevant past information when starting a task related to prior work.

```bash
agent-memory search --query "<topic>" --mode keyword
```

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

### Install Skills for Cross-Agent Integration

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

This command wires memory into various agents like Claude Code, Codex, Cursor, and Agent CLI, enabling prompt injection and seamless memory recall across different tools.

```bash
agent-memory install-skills
```

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

### Avoid Long-Term Entries for Daily Logs

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

This example demonstrates an incorrect use of the long-term entry command for a daily log item. Long-term entries should only contain durable facts.

```bash
# Bad — this is a daily log entry, not a durable fact
agent-memory write --target long_term --content "Fixed the deploy script today"
```

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

### Initialize Agent Memory Store

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Run this command to create the necessary memory directory and optionally integrate with qmd for enhanced functionality. This sets up the local storage for your agent's memory.

```bash
agent-memory init
```

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

### Run Unit Tests

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Execute unit tests for utilities, scratchpad parsing, context builder, qmd helpers, and tool functions. These tests are fast and deterministic as they do not involve LLMs or qmd.

```bash
# Unit tests (no LLM, no qmd — fast, deterministic)
bun test test/unit.test.ts
bun test test/cli.test.ts
```

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

### Context Injection Priority and Budget

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

This table outlines the priority order, budget allocation, and truncation strategy for different sections when assembling context for an agent. It details how the 16K character limit is managed.

```text
  Priority    Section                      Budget    Truncation
  --------    -------                      ------    ----------
  1 (high)    Open scratchpad items        2.0K      from start
  2           Recent topic entries         2.0K      from start
  3           Today's daily log            3.0K      from end (tail)
  4           qmd search results           2.5K      from start
  5           MEMORY.md (long-term)        4.0K      from middle
  6 (low)     Yesterday's daily log        3.0K      from end (tail)
                                          ------
                                          16.5K (individual caps)
                                          16.0K (total cap)
```

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

### Build Agent Memory CLI from Source

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Build the Agent Memory CLI from source code using bun. This command produces the CLI in the dist/agent-memory directory.

```bash
# Or build from source
bun run build:cli
# => produces dist/agent-memory
```

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

### Build and Test CLI

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Build the Command Line Interface (CLI) binary for Agent Memory and test its basic write and read functionalities. This involves creating the executable and then performing a simple data write and read operation.

```bash
# Build the CLI binary
bun run build:cli

# Test CLI
agent-memory write --target long_term --content "test" && agent-memory read --target long_term
```

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

### Initialize Agent Memory Directory

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Run this command to initialize the memory directory for Agent Memory.

```bash
# Initialize memory directory
agent-memory init
```

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

### Publish to npm

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Prepare and publish a new version of the Agent Memory package to the npm registry. This includes confirming package name availability, version bumping, and publishing with public access.

```bash
# Confirm package name is available
npm view myagentmemory

# Bump version (choose patch/minor/major)
npm version patch

# Publish to npm (public)
npm publish --access public
```

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

### Write a Specific Daily Log Entry

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Use this command to record specific actions and learnings, including relevant tags for organization. Ensure entries are concise and informative.

```bash
# Good — specific, searchable, tagged
agent-memory write --content "Refactored auth middleware to use jose instead of jsonwebtoken. Reduced bundle by 40KB. #refactor #auth"
```

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

### Build CLI Binary

Source: https://github.com/jayzeng/agentmemory/blob/main/CLAUDE.md

Builds the command-line interface binary for the agent memory system. This command is essential for creating an executable version of the CLI.

```bash
# Build the CLI binary
bun run build:cli
```

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

### Run Unit Tests

Source: https://github.com/jayzeng/agentmemory/blob/main/CLAUDE.md

Executes unit tests for the agent memory system. These tests do not require an LLM or qmd and focus on utilities, scratchpad parsing, context builder, qmd helpers, and tool functions.

```bash
# Run unit tests (no LLM, no qmd)
bun test test/unit.test.ts
```

```bash
bun test test/cli.test.ts
```

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

### Run CLI Integration Tests

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Execute Level 2 CLI integration tests using bun:test. These tests verify core functions by direct import and by invoking the agent-memory binary as a subprocess, without requiring an LLM.

```bash
bun test test/cli.test.ts
```

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

### Manage Scratchpad (TODOs)

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Adds, lists, marks as done, or removes items from a persistent TODO list. Matches are typically done by substring.

```bash
agent-memory scratchpad add --text "Review PR #42"
agent-memory scratchpad list
agent-memory scratchpad done --text "PR #42"       # Matches by substring
agent-memory scratchpad undo --text "PR #42"
agent-memory scratchpad clear_done                  # Remove completed items
```

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

### Write a Good Daily Log Entry

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/codex/SKILL.md

Use specific, searchable content with relevant tags for daily log entries. This helps in organizing and retrieving information later.

```bash
# Good — specific, searchable, tagged
agent-memory write --content "Refactored auth middleware to use jose instead of jsonwebtoken. Reduced bundle by 40KB. #refactor #auth"
```

```bash
# Bad — too vague, no tags
agent-memory write --content "worked on auth stuff"
```

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

### Selective Injection Flow

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Illustrates the process of searching for relevant memories, sanitizing and checking them, performing a qmd search, and injecting the formatted result into the system prompt. This flow ensures the agent receives context without direct tool calls.

```text
  User: "what database should we use?"
         |
         v
  searchRelevantMemories("what database should we use?")
         |
         +-- sanitize: strip control chars, limit to 200 chars
         +-- check: qmd available? collection exists?
         +-- qmd search "what database should we use?" -n 3 -c agent-memory
         +-- timeout: 3 seconds (Promise.race)
         +-- format: markdown snippets with file paths
         |
         v
  Result: "#decision [[database-choice]] Chose PostgreSQL for all
           backend services. Evaluated MySQL and MongoDB..."
         |
         v
  Injected into system prompt under "## Relevant memories (auto-retrieved)"
```

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

### Markdown Conventions for Searchability

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Utilize markdown tags and wiki-links within memory content to enhance searchability. These conventions are indexed by qmd for free.

```markdown
#decision [[database-choice]] Chose PostgreSQL for all backend services.
#preference [[editor]] User prefers Neovim with LazyVim config.
#lesson [[api-versioning]] URL prefix versioning (/v1/) avoids CDN cache issues.
```

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

### Preview Distillation of MEMORY.md

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Use the `--dry-run` flag with the `distil` command to preview the changes to MEMORY.md without actually writing them. This is useful for verifying the distillation process.

```bash
agent-memory distil --dry-run   # Preview without writing
```

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

### Write to Daily Log

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Use this command to log session notes, progress, bugs, and decisions. No specific target is needed as it defaults to the daily log.

```bash
# Session notes, progress, bugs found, decisions made
agent-memory write --content "Fixed auth bug in login.ts — token refresh was missing"
agent-memory write --content "Investigated slow queries — N+1 in getUserOrders, added .include(:orders)"
```

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

### Distil MEMORY.md - Preview and Execute

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/codex/SKILL.md

Use the `distil` command to preview changes to MEMORY.md without writing them, or to overwrite MEMORY.md with a distilled index. This process helps in auto-curating the memory file.

```bash
agent-memory distil --dry-run   # Preview without writing
```

```bash
agent-memory distil             # Overwrite MEMORY.md with distilled index
```

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

### Run Deterministic Unit Tests

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Execute Level 1 deterministic unit tests using bun:test. These tests verify core logic in isolation, without LLM, qmd, or network dependencies, using temporary directories and path overrides.

```bash
bun test test/unit.test.ts
```

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

### Write to Topic/Event File

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Logs events or themes with backlinks to the daily entry. Useful for organizing information by specific topics.

```bash
# Event- or theme-based log with backlinks to the daily entry
agent-memory write --target topic --topic "auth" --content "JWT refresh rolled out to edge #auth"
```

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

### Manage Topic Notes with Agent Memory CLI

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Use the agent-memory CLI to write new topic notes or read existing ones. You can target specific topics or list all topics.

```bash
agent-memory write --target topic --topic "auth" --content "JWT refresh rolled out to edge #auth"
agent-memory read --target topic --topic "auth"
agent-memory read --target topics
```

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

### Write a Good Long-Term Entry

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/codex/SKILL.md

Use long-term entries for facts that should persist across all sessions. Include tags and links for better organization. Avoid daily log details here.

```bash
# Good — this belongs in every session
agent-memory write --target long_term --content "Deploy: 'bun run deploy:prod', requires AWS_PROFILE=prod. #ops [[deploy]]"
```

```bash
# Bad — this is a daily log entry, not a durable fact
agent-memory write --target long_term --content "Fixed the deploy script today"
```

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

### Search Modes Mapping

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

Tabular representation of the different search modes supported by the `memory_search` tool, mapping each mode to its corresponding qmd command and primary use case. All modes share default parameters but have specific configurations for selective injection.

```text
  Mode        qmd command   Use case
  --------    -----------   --------
  keyword     search        Fast BM25 lookup (~30ms). Default.
  semantic    vsearch       Vector similarity when wording differs from stored text.
  deep        query         LLM-powered query for complex questions. Slowest.
```

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

### Add Scratchpad Entry

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Add an entry to the agent's scratchpad. The scratchpad is for temporary thoughts or intermediate steps.

```javascript
await memory.add("scratchpad", "I need to find a python sorting algorithm.");
```

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

### Uninstall Skill Files

Source: https://github.com/jayzeng/agentmemory/blob/main/README.md

Use this command to uninstall skill files for agents.

```bash
# Uninstall skill files
agent-memory uninstall-skills
```

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

### Initialize Agent Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Initialize Agent Memory with a specific name. This creates a new memory instance for your agent.

```javascript
import { AgentMemory } from "myagentmemory";

const memory = new AgentMemory("my-agent-memory");
```

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

### Agent Memory Architecture Diagram

Source: https://github.com/jayzeng/agentmemory/blob/main/design.md

This diagram illustrates the flow of information and processes within the Agent Memory system, from user prompt to agent turn and subsequent memory updates.

```text
                              +------------------+
                              |   User Prompt    |
                              +--------+---------+
                                       |
                          +------------v-------------+
                          |   Context injection      |
                          |                          |
                          |  1. searchRelevantMemories(prompt)
                          |     - sanitize prompt    |
                          |     - qmd search (3s timeout)
                          |     - format top 3 results
                          |                          |
                          |  2. buildMemoryContext(searchResults)
                          |     - read scratchpad    |
                          |     - read today's daily |
                          |     - include search results
                          |     - read MEMORY.md     |
                          |     - read yesterday's daily
                          |     - truncate to 16K    |
                          |                          |
                          |  3. Append to system prompt
                          +------------+-------------+
                                       |
                              +--------v---------+
                              |   Agent Turn     |
                              |                  |
                              |  Tools available:|
                              |  - memory_write  |
                              |  - memory_read   |
                              |  - scratchpad    |
                              |  - memory_search |
                              +--------+---------+
                                       |
                              +--------v---------+
                              |  After writes:   |
                              |  debounced       |
                              |  qmd update      |
                              |  (500ms, async)  |
                              +------------------+
```

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

### Search Memory Semantically

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Use this command to perform a semantic search for specific information within your agent's memory. It retrieves relevant markdown content based on the query.

```bash
agent-memory search --query "how do we version the API" --mode semantic
```

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

### Distil and Overwrite MEMORY.md

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Run the `distil` command without flags to automatically curate MEMORY.md by grouping daily logs and topics by tags. This command overwrites the existing MEMORY.md.

```bash
agent-memory distil             # Overwrite MEMORY.md with distilled index
```

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

### Search for Relevant Memories

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/agent/SKILL.md

If the user's task relates to prior work, use this command to search for relevant memories. Replace '<topic>' with the relevant subject.

```bash
agent-memory search --query "<topic>" --mode keyword

```

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

### Add Log Entry

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Add a log entry to the agent's memory. Logs are timestamped records of events or interactions.

```javascript
await memory.add("log", "User asked for a python script.");
```

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

### Retrieve Current Memory Context

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Fetches the current memory context without performing a search. Errors are redirected to null.

```bash
agent-memory context --no-search 2>/dev/null
```

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

### Search Memory Contents

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Recalls past work by searching logs. Supports fast keyword search, semantic search for related concepts, and deep search with reranking.

```bash
agent-memory search --query "database choice" --mode keyword    # Fast keyword
agent-memory search --query "how we handle auth" --mode semantic # Finds related concepts
agent-memory search --query "performance" --mode deep --limit 10 # Hybrid + reranking
```

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

### Write a Durable Long-Term Fact

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Use the `--target long_term` flag to record facts that are essential for every session. Include tags and links for better context and organization.

```bash
# Good — this belongs in every session
agent-memory write --target long_term --content "Deploy: 'bun run deploy:prod', requires AWS_PROFILE=prod. #ops [[deploy]]"
```

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

### Recall from Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Recall information from the agent's memory. This can be used to retrieve facts, logs, notes, or scratchpad entries.

```javascript
const facts = await memory.recall("fact");
const logs = await memory.recall("log");
const notes = await memory.recall("note");
const scratchpad = await memory.recall("scratchpad");
```

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

### Write to Long-Term Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/codex/SKILL.md

For durable facts that belong in every session's context. Prefer overwrite mode to curate the entire file rather than appending.

```bash
# Only for durable facts that belong in every session's context
agent-memory write --target long_term --content "Project uses Drizzle ORM with PostgreSQL. Migrations in db/migrations/. #architecture"
```

```bash
# Overwrite MEMORY.md entirely (for curation — rewrite, don't append)
agent-memory write --target long_term --content "..." --mode overwrite
```

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

### Read Memory Contents

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Retrieves logged information from various memory targets. Supports reading specific dates, all daily logs, topics, long-term memory, and the scratchpad.

```bash
agent-memory read --target daily             # Today's log
agent-memory read --target daily --date 2026-02-15  # Specific day
agent-memory read --target list              # All daily log files
agent-memory read --target topic --topic "auth"
agent-memory read --target topics            # All topic files
agent-memory read --target long_term         # MEMORY.md
agent-memory read --target scratchpad        # Scratchpad checklist
```

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

### Add Note to Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Add a note to the agent's memory. Notes are unstructured text entries that can be searched.

```javascript
await memory.add("note", "The user wants a python script that sorts a list.");
```

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

### Clear Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Clear all data from the agent's memory. Use with caution as this action is irreversible.

```javascript
await memory.clear();
```

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

### Write to Long-Term Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/skills/claude-code/SKILL.md

Use for durable facts that belong in every session's context. Prefer overwrite mode to curate the entire file rather than appending.

```bash
# Only for durable facts that belong in every session's context
agent-memory write --target long_term --content "Project uses Drizzle ORM with PostgreSQL. Migrations in db/migrations/. #architecture"

# Overwrite MEMORY.md entirely (for curation — rewrite, don't append)
agent-memory write --target long_term --content "..." --mode overwrite
```

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

### Add Fact to Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Add a fact to the agent's memory. Facts are key-value pairs that the agent can recall.

```javascript
await memory.add("fact", "The user wants a python script.");
```

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

### Delete Memory

Source: https://github.com/jayzeng/agentmemory/blob/main/docs/index.html

Delete a specific memory instance. This removes all data associated with that memory.

```javascript
await memory.delete();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.