agentic-memorizer

command module
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2025 License: MIT Imports: 3 Imported by: 0

README

Agentic Memorizer

Go Version Go Report Card GitHub Release CI E2E Tests

A framework-agnostic AI agent memory system that provides automatic awareness and understanding of files in your memory directory through AI-powered semantic analysis. Features native automatic integration for Claude Code (hooks + MCP), Gemini CLI (hooks + MCP), and OpenAI Codex CLI (MCP).

Current Version: v0.12.1 (CHANGELOG.md)

Table of Contents

Overview

Agentic Memorizer provides AI agents with persistent, semantic awareness of your local files. Instead of manually managing which files to include in context or repeatedly explaining what files exist, your AI agent automatically receives a comprehensive, AI-powered index showing what files you have, what they contain, their purpose, and how to access them.

Works seamlessly with Claude Code, Gemini CLI, and Codex CLI with automatic setup.

How It Works

A background daemon continuously watches your designated memory directory (~/.memorizer/memory/ by default), automatically discovering and analyzing files as they're added or modified. Each file is processed to extract metadata (word counts, dimensions, page counts, etc.) and—using the Claude API—semantically analyzed to understand its content, purpose, and key topics. This information is maintained in a precomputed index that loads quickly when your AI agent starts.

When you launch your AI agent, the precomputed index is loaded into its context:

  • Claude Code & Gemini CLI: SessionStart hooks automatically load the index
  • Other frameworks: Configure your agent to run the read command on startup

Your AI agent can then:

  • Discover what files exist without you listing them
  • Understand file content and purpose before reading them
  • Decide which files to access based on semantic relevance
  • Access files efficiently using the appropriate method (Read tool for text/code/images, extraction for PDFs/docs)
Key Capabilities

Automatic File Management:

  • Discovers files as you add them to the memory directory
  • Updates the index automatically when files are modified or deleted
  • Maintains a complete catalog without manual intervention

Semantic Understanding:

  • AI-powered summaries of file content and purpose
  • Semantic tags and key topics for each file
  • Document type classification (e.g., "technical-guide", "architecture-diagram")
  • Vision analysis for images using Claude's multimodal capabilities

Efficiency:

  • Background daemon handles all processing asynchronously
  • Smart caching only re-analyzes changed files
  • Precomputed index enables quick Claude Code startup
  • Minimal API usage—only new/modified files are analyzed

Wide Format Support:

  • Direct reading: Markdown, text, JSON/YAML, code files, images, VTT transcripts
  • Extraction supported: Word documents (DOCX), PowerPoint (PPTX), PDFs
  • Automatic metadata extraction for all file types

Integration:

  • Framework-agnostic with native support for multiple AI agent frameworks
  • Automatic setup for Claude Code, Gemini CLI, and Codex CLI
  • Configurable output formats (XML, Markdown, JSON)
  • Integration management commands for detection, setup, validation, and health checks
  • Optional health monitoring and logging

Why Use This?

Instead of:

  • ✗ Manually copying file contents into prompts
  • ✗ Pre-loading all files into context (wasting tokens)
  • ✗ Repeatedly explaining what files exist to Claude
  • ✗ Managing which files to include/exclude manually

You get:

  • ✓ Automatic file awareness on every session
  • ✓ Smart, on-demand file access (AI agent decides what to read)
  • ✓ Semantic understanding of content before reading
  • ✓ Efficient token usage (only index, not full content)
  • ✓ Works across sessions with persistent cache

Supported AI Agent Frameworks

Agentic Memorizer integrates with multiple AI agent frameworks, providing automatic setup for all supported frameworks.

Automatic Integration

Claude Code - Full automatic integration with one-command setup

  • Automatic framework detection and configuration
  • One-command setup: memorizer integrations setup claude-code-hook
  • SessionStart hook configuration with all matchers (startup, resume, clear, compact)
  • Default XML output with JSON envelope wrapping for proper hook formatting
  • Full lifecycle management (setup, update, remove, validate)

Gemini CLI - Full automatic integration with SessionStart hooks and MCP server

  • Automatic framework detection and configuration
  • SessionStart hook setup: memorizer integrations setup gemini-cli-hook
  • MCP server setup: memorizer integrations setup gemini-cli-mcp
  • Hook configuration with matchers (startup, resume, clear)
  • MCP server provides five on-demand tools: search_files, get_file_metadata, list_recent_files, get_related_files, search_entities
  • Full lifecycle management (setup, update, remove, validate)
  • Works with both user and project-level Gemini CLI configurations

OpenAI Codex CLI - MCP server integration with automatic setup

  • Automatic framework detection and configuration
  • One-command setup: memorizer integrations setup codex-cli-mcp
  • MCP server configuration in ~/.codex/config.toml (TOML format)
  • Provides five on-demand tools: search_files, get_file_metadata, list_recent_files, get_related_files, search_entities
  • Full lifecycle management (setup, update, remove, validate)
  • Verification via /mcp command in Codex TUI
Framework Comparison
Feature Claude Code (Hook) Claude Code (MCP) Gemini CLI (Hook) Gemini CLI (MCP) Codex CLI (MCP)
Setup Type Automatic Automatic Automatic Automatic Automatic
Delivery SessionStart injection On-demand tools SessionStart injection On-demand tools On-demand tools
Output Format XML (JSON-wrapped) N/A (tool-based) XML (JSON-wrapped) N/A (tool-based) N/A (tool-based)
Best For Complete awareness Large directories Complete awareness Large directories Large directories
Validation Automatic Automatic Automatic Automatic Automatic

Architecture

Three-Phase Processing Pipeline:

  1. Metadata Extraction (internal/metadata/) - Fast, deterministic extraction using specialized handlers for 9 file type categories
  2. Semantic Analysis (internal/semantic/) - AI-powered content understanding via Claude API with entity extraction
  3. Knowledge Graph Storage (internal/graph/) - FalkorDB graph database for relationships and semantic search

Background Daemon (internal/daemon/):

  • Walker (internal/walker/) - Full directory scans during rebuilds
  • File Watcher (internal/watcher/) - Real-time monitoring with fsnotify
  • Worker Pool - Parallel processing with rate limiting (default 3 workers, 20 calls/min)
  • HTTP API (internal/daemon/api/) - RESTful endpoints and SSE for real-time updates:
    • GET /health - Health check with metrics
    • GET /sse - Server-Sent Events stream
    • GET /api/v1/index - Full memory index
    • POST /api/v1/search - Semantic search
    • GET /api/v1/files/{path} - File metadata
    • GET /api/v1/files/recent - Recent files
    • GET /api/v1/files/related - Related files
    • GET /api/v1/entities/search - Entity search
    • POST /api/v1/rebuild - Trigger rebuild

Knowledge Graph (internal/graph/):

  • FalkorDB (Redis-compatible graph database)
  • Node types: File, Tag, Topic, Entity, Category, Directory
  • Relationship types: HAS_TAG, COVERS_TOPIC, MENTIONS, IN_CATEGORY, REFERENCES, SIMILAR_TO, IN_DIRECTORY, PARENT_OF
  • Vector embeddings for semantic similarity (optional, requires OpenAI API)

Semantic Search (internal/search/):

  • Graph-powered Cypher queries
  • Full-text search on summaries
  • Entity-based file discovery
  • Related file traversal
  • Tag and topic filtering

Integration Framework (internal/integrations/):

  • Adapter pattern for Claude Code (hook + MCP), Gemini CLI, Codex CLI
  • Independent output processors (XML, Markdown, JSON)

MCP Server (internal/mcp/):

  • JSON-RPC 2.0 stdio transport
  • Five tools: search_files, get_file_metadata, list_recent_files, get_related_files, search_entities
  • Connects to daemon HTTP API for graph queries

Configuration (internal/config/):

  • Layered: defaults → YAML → environment variables
  • Hot-reload support via config reload command

The daemon handles all processing in the background, so AI agent startup remains quick regardless of file count.

FalkorDB Knowledge Graph

Agentic Memorizer uses FalkorDB as its storage backend, providing a knowledge graph that captures relationships between files, tags, topics, and entities.

Why a Knowledge Graph?

Unlike flat file indexes, a knowledge graph enables:

  • Relationship Discovery: Find files that share tags, topics, or mention the same entities
  • Semantic Search: Query by meaning, not just keywords
  • Entity-Based Navigation: "Find all files mentioning Terraform" or "What files reference this API?"
  • Related File Suggestions: Discover files connected through shared concepts
Starting FalkorDB

FalkorDB runs as a Docker container. Start it before the daemon:

# Start FalkorDB container (pulls image on first run)
memorizer graph start

# Check status
memorizer graph status

# Stop when done
memorizer graph stop

Or use docker-compose:

docker-compose up -d      # Start FalkorDB
docker-compose down       # Stop FalkorDB
Graph Commands
# Start FalkorDB Docker container
memorizer graph start [--detach]

# Stop FalkorDB container
memorizer graph stop [--remove]

# Check FalkorDB status and graph statistics
memorizer graph status

To rebuild the graph, use memorizer daemon rebuild [--force].

Graph Configuration

In ~/.memorizer/config.yaml:

graph:
  enabled: true              # Enable graph storage
  host: localhost            # FalkorDB host
  port: 6379                 # FalkorDB port (Redis protocol)
  database: memorizer        # Graph database name
Browser UI

FalkorDB includes a browser-based UI for exploring the graph:

http://localhost:3000
Data Persistence

FalkorDB stores data at /data inside the container, which is bind-mounted to ~/.memorizer/falkordb/. Persistence files (dump.rdb) appear in this directory after data is saved.

Clearing graph data:

# Option A: Delete persistence files and restart (simplest)
rm -rf ~/.memorizer/falkordb/*
docker restart memorizer-falkordb

# Option B: Clear and rebuild via daemon
memorizer daemon rebuild --force

# Option C: Remove and recreate container
docker stop memorizer-falkordb && docker rm memorizer-falkordb
memorizer graph start
FalkorDB Availability

IMPORTANT: The daemon requires FalkorDB to be running at startup and cannot operate without it.

If FalkorDB is unavailable:

  • Daemon initialization will fail with "failed to initialize graph"
  • You must start FalkorDB before starting the daemon
  • Use memorizer graph start to launch the FalkorDB container

If an index rebuild fails but existing graph data is present, the daemon will continue running with the existing data (degraded mode). However, this does not apply to FalkorDB connection failures.

Quick Start

Get up and running quickly with your AI agent:

1. Install
go install github.com/leefowlercu/agentic-memorizer@latest
2. Set API Key
export ANTHROPIC_API_KEY="your-key-here"
3. Start FalkorDB
# Start the knowledge graph database (requires Docker)
memorizer graph start
4. Choose Your Integration Path
Path A: Claude Code (Automatic Integration)

For Claude Code users, automatic setup configures everything for you:

memorizer initialize --integrations claude-code-hook,claude-code-mcp

This will:

  • Create config at ~/.memorizer/config.yaml
  • Create memory directory at ~/.memorizer/memory/
  • Automatically configure Claude Code SessionStart hooks and MCP Server integration (no manual editing required)

Then start the daemon:

memorizer daemon start
# OR set up as system service (recommended):
memorizer daemon systemctl  # Linux
memorizer daemon launchctl  # macOS
Path B: Gemini CLI (Automatic Integration)

For Gemini CLI users, automatic setup works the same way:

memorizer initialize --integrations gemini-cli-hook,gemini-cli-mcp

This will:

  • Create config at ~/.memorizer/config.yaml
  • Create memory directory at ~/.memorizer/memory/
  • Automatically configure Gemini CLI SessionStart hooks and MCP Server integration (no manual editing required)

Then start the daemon:

memorizer daemon start
Path C: Manual Setup (All Other Frameworks)

For other frameworks or manual configuration:

memorizer initialize
# Then manually configure your agent framework (see Integration Setup section)
5. Add Files to Memory
# Add any files you want your AI agent to be aware of
cp ~/important-notes.md ~/.memorizer/memory/
cp ~/project-docs/*.pdf ~/.memorizer/memory/documents/

The daemon will automatically detect and index these files.

6. Start Your AI Agent

Claude Code:

claude

Gemini CLI:

gemini

Both frameworks automatically load the memory index via SessionStart hooks.

Other Frameworks:

Start your agent normally. The memory index will load based on the configuration you set up in step 4.

Your AI agent now automatically knows about all files in your memory directory!

For detailed installation options, configuration, and advanced usage, see the sections below.

Installation

Prerequisites
  • Go 1.25.1 or later
  • Docker (for FalkorDB knowledge graph)
  • Claude API key (get one here)
  • An AI agent framework: Claude Code, Gemini CLI, or Codex CLI
Build and Install
go install github.com/leefowlercu/agentic-memorizer@latest

Then run the initialize command to set up configuration:

# Interactive setup (prompts for integrations)
memorizer initialize

# Or with flags for automated setup
memorizer initialize --integrations claude-code-hook,claude-code-mcp

This creates:

  • Config file at ~/.memorizer/config.yaml
  • Memory directory at ~/.memorizer/memory/
  • Cache directory at ~/.memorizer/.cache/ (for semantic analysis cache)
  • Graph database (populated by daemon on first run in FalkorDB)

The initialize command can optionally configure AI agent integrations automatically with --integrations <integration-name>.

After initialization, start the daemon:

memorizer daemon start
# OR set up as system service (recommended for production):
memorizer daemon systemctl  # Linux
memorizer daemon launchctl  # macOS
Option 2: Using Makefile
# Build and install
make install

This will:

  • Build the memorizer binary with version info from git
  • Install it to ~/.local/bin/memorizer

The build automatically injects version information from git tags and commits, providing accurate version tracking in logs and index files.

Configuration

Set your API key via environment variable (recommended):

export ANTHROPIC_API_KEY="your-key-here"

Or edit ~/.memorizer/config.yaml:

claude:
  api_key: "your-api-key-here"

Custom Setup:

# Custom memory directory
memorizer initialize --memory-root ~/my-memory

# Custom cache directory
memorizer initialize --cache-dir ~/my-memory/.cache

# Force overwrite existing config
memorizer initialize --force

Integration Setup

Claude Code Integration (Automatic)

Claude Code enjoys full automatic integration support with one-command setup.

memorizer integrations setup claude-code-hook

This command automatically:

  1. Detects your Claude Code installation (~/.claude/ directory)
  2. Creates or updates ~/.claude/settings.json
  3. Preserves existing settings (won't overwrite other configurations)
  4. Adds SessionStart hooks for all matchers (startup, resume, clear, compact)
  5. Configures the command: memorizer read --format xml --integration claude-code-hook
  6. Creates backup at ~/.claude/settings.json.backup

You can also use the --integrations flag during initialization:

memorizer initialize --integrations
memorizer daemon start
Manual Setup (Alternative)

If you prefer manual configuration, add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/memorizer read --format xml --integration claude-code-hook"
          }
        ]
      }
      // Repeat for "resume", "clear", and "compact" matchers
    ]
  }
}

Note: Include all four SessionStart matchers to ensure the memory index loads throughout your session lifecycle.

Validation

Verify your setup:

memorizer integrations health
Removal

Remove the integration:

memorizer integrations remove claude-code-hook
Claude Code MCP Integration (Automatic)

Claude Code also supports integration via the Model Context Protocol (MCP), providing advanced semantic search capabilities through MCP tools.

memorizer integrations setup claude-code-mcp

This command automatically:

  1. Detects your Claude Code installation (~/.claude/ directory)
  2. Creates or updates ~/.claude.json (MCP server configuration)
  3. Registers the memorizer MCP server
  4. Configures environment variables (MEMORIZER_MEMORY_ROOT)
  5. Sets the binary command path
  6. Creates backup at ~/.claude.json.backup
MCP Tools and Prompts

The MCP server exposes five tools and three prompt templates for interacting with your memory index. For detailed information on each tool, prompt, and how to use them, see the Using the MCP Server section.

Available MCP Tools:

  • search_files - Semantic search across indexed files
  • get_file_metadata - Complete metadata for a specific file
  • list_recent_files - Recently modified files
  • get_related_files - Files connected through shared tags/topics/entities (requires FalkorDB)
  • search_entities - Files mentioning specific entities (requires FalkorDB)

Available MCP Prompts:

  • analyze-file - Generate detailed file analysis
  • search-context - Build effective search queries
  • explain-summary - Understand semantic analysis results
MCP Configuration

The MCP server has dedicated configuration in config.yaml:

mcp:
  log_file: ~/.memorizer/mcp.log  # MCP server logs
  log_level: info                          # Log level (debug/info/warn/error)
Running the MCP Server

The MCP server is automatically started by Claude Code when configured. You can also run it manually for testing:

# Start MCP server in stdio mode
memorizer mcp start

# Start with debug logging
memorizer mcp start --log-level debug

# View MCP logs
tail -f ~/.memorizer/mcp.log

The server communicates via stdin/stdout using JSON-RPC 2.0 protocol.

MCP vs SessionStart Hooks

You can use one or both Claude Code integration methods:

  • SessionStart Hooks (claude-code-hook): Injects full memory index at session start

    • Best for: Always-available context, complete file awareness
    • Trade-off: Larger initial context, all files loaded upfront

  • MCP Server (claude-code-mcp): Provides on-demand tools for semantic search

    • Best for: Large memory directories, selective file discovery
    • Trade-off: Requires explicit tool use, context fetched on demand

Many users enable both for maximum flexibility.

Validation

Verify your MCP setup:

memorizer integrations health
memorizer integrations health
Removal

Remove the MCP integration:

memorizer integrations remove claude-code-mcp
Gemini CLI SessionStart Hook Integration (Automatic)

Gemini CLI supports SessionStart hook integration for automatic memory index loading, similar to Claude Code.

memorizer integrations setup gemini-cli-hook

This command automatically:

  1. Detects your Gemini CLI installation (~/.gemini/ directory)
  2. Creates or updates ~/.gemini/settings.json
  3. Preserves existing settings (won't overwrite other configurations)
  4. Adds SessionStart hooks for all matchers (startup, resume, clear)
  5. Configures the command: memorizer read --format xml --integration gemini-cli-hook
  6. Creates backup at ~/.gemini/settings.json.backup

You can also use the --integrations flag during initialization:

memorizer initialize --integrations gemini-cli-hook
memorizer daemon start
Manual Setup (Alternative)

If you prefer manual configuration, add to ~/.gemini/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "name": "memorizer-hook",
            "type": "command",
            "command": "/path/to/memorizer read --format xml --integration gemini-cli-hook",
            "description": "Load agentic memory index"
          }
        ]
      }
      // Repeat for "resume" and "clear" matchers
    ]
  }
}

Note: Gemini CLI supports three SessionStart matchers: startup, resume, and clear.

Hook Output Format

The Gemini CLI hook integration uses a simpler JSON envelope compared to Claude Code:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "<memory_index>...</memory_index>"
  }
}
  • hookEventName: Always "SessionStart"
  • additionalContext: Contains the full index (XML, Markdown, or JSON) that Gemini CLI adds to the context window
Validation

Verify your setup:

memorizer integrations health
Removal

Remove the integration:

memorizer integrations remove gemini-cli-hook
OpenAI Codex CLI Integration (Automatic)

OpenAI Codex CLI supports integration via the Model Context Protocol (MCP), providing semantic search and metadata retrieval tools.

Setup

One-command automatic setup:

memorizer integrations setup codex-cli-mcp

What it does:

  1. Detects your Codex CLI installation (~/.codex/ directory)
  2. Creates/updates ~/.codex/config.toml with MCP server configuration
  3. Configures the binary path and memory root environment variable
  4. Enables the MCP server by default

Configuration:

The setup command adds an MCP server entry to your Codex CLI configuration:

[mcp_servers.memorizer]
command = "/path/to/memorizer"
args = ["mcp", "start"]
enabled = true

[mcp_servers.memorizer.env]
MEMORIZER_MEMORY_ROOT = "/path/to/memory"

MCP Tools:

The MCP server exposes five tools to Codex CLI:

  • search_files: Semantic search across indexed files

    • Query by filename, tags, topics, or summary content
    • Returns ranked results with relevance scores
    • Optional category filtering

  • get_file_metadata: Retrieve complete metadata for specific files

    • Full semantic analysis (summary, tags, topics, document type)
    • File metadata (size, type, category, modification date)
    • Confidence scores and analysis results

  • list_recent_files: List recently modified files

    • Configurable time window (1-365 days)
    • Sorted by modification date
    • Optional result limit

  • get_related_files: Find files connected through shared concepts

    • Discovers files with shared tags, topics, or entities
    • Ranks by connection strength
    • Enables knowledge graph traversal

  • search_entities: Search for files mentioning specific entities

    • Find files referencing people, organizations, concepts
    • Supports entity type filtering
    • Returns files with entity mention details

Verification:

Run Codex CLI and use the /mcp command to verify the integration:

codex
# In Codex TUI, type:
/mcp

You should see memorizer listed as an active MCP server.

Alternatively, validate via CLI:

memorizer integrations health

Removal:

Remove the MCP integration:

memorizer integrations remove codex-cli-mcp
Gemini CLI MCP Integration (Automatic)

Gemini CLI supports integration via the Model Context Protocol (MCP), providing semantic search and metadata retrieval tools.

Setup

One-command automatic setup:

memorizer integrations setup gemini-cli-mcp

What it does:

  1. Detects your Gemini CLI installation (~/.gemini/ directory)
  2. Creates/updates ~/.gemini/settings.json with MCP server configuration
  3. Configures the binary path and memory root environment variable
  4. Enables the MCP server by default

Configuration:

The setup command adds an MCP server entry to your Gemini CLI configuration:

{
  "mcpServers": {
    "memorizer": {
      "command": "/path/to/memorizer",
      "args": ["mcp", "start"],
      "env": {
        "MEMORIZER_MEMORY_ROOT": "/path/to/memory"
      }
    }
  }
}

MCP Tools:

The MCP server exposes five tools to Gemini CLI:

  • search_files: Semantic search across indexed files

    • Query by filename, tags, topics, or summary content
    • Returns ranked results with relevance scores
    • Optional category filtering

  • get_file_metadata: Retrieve complete metadata for specific files

    • Full semantic analysis (summary, tags, topics, document type)
    • File metadata (size, type, category, modification date)
    • Confidence scores and analysis results

  • list_recent_files: List recently modified files

    • Configurable time window (1-365 days)
    • Sorted by modification date
    • Optional result limit

  • get_related_files: Find files connected through shared concepts

    • Discovers files with shared tags, topics, or entities
    • Ranks by connection strength
    • Enables knowledge graph traversal

  • search_entities: Search for files mentioning specific entities

    • Find files referencing people, organizations, concepts
    • Supports entity type filtering
    • Returns files with entity mention details

Verification:

Validate via CLI:

memorizer integrations health

Removal:

Remove the MCP integration:

memorizer integrations remove gemini-cli-mcp

Managing Integrations

The integrations command group provides comprehensive tools for managing integrations with various AI agent frameworks.

List Available Integrations
memorizer integrations list

Shows all registered integrations with their status and configuration:

Example Output:

✓ claude-code-hook
  Description: Claude Code SessionStart hooks integration
  Version:     2.0.0
  Status:      configured

✓ claude-code-mcp
  Description: Claude Code MCP server integration
  Version:     2.0.0
  Status:      configured

✓ gemini-cli-hook
  Description: Gemini CLI SessionStart hook integration
  Version:     1.0.0
  Status:      configured

✓ gemini-cli-mcp
  Description: Gemini CLI MCP server integration
  Version:     2.0.0
  Status:      configured

✓ codex-cli-mcp
  Description: OpenAI Codex CLI MCP server integration
  Version:     2.0.0
  Status:      configured
Detect Installed Frameworks

Automatically detect which agent frameworks are installed on your system:

memorizer integrations detect

Example Output:

Detected Frameworks:
  ✓ claude-code-hook (installed at ~/.claude)

Checks for framework-specific configuration directories and files.

Setup an Integration
Automatic Setup

All supported integrations offer automatic setup:

# Claude Code SessionStart hooks
memorizer integrations setup claude-code-hook

# Claude Code MCP server
memorizer integrations setup claude-code-mcp

# Gemini CLI SessionStart hooks
memorizer integrations setup gemini-cli-hook

# Gemini CLI MCP server
memorizer integrations setup gemini-cli-mcp

# Codex CLI MCP server
memorizer integrations setup codex-cli-mcp

# With custom binary path
memorizer integrations setup claude-code-hook --binary-path /custom/path/memorizer

Setup automatically:

  • Detects the framework's configuration file
  • Adds appropriate integration configuration
  • Preserves existing settings and creates backup
  • Validates the configuration
Remove an Integration
memorizer integrations remove claude-code-hook
memorizer integrations remove claude-code-mcp
memorizer integrations remove gemini-cli-hook
memorizer integrations remove gemini-cli-mcp

Removes the integration configuration from the framework's settings file. For hook integrations, this:

  • Removes SessionStart hooks added by memorizer
  • Preserves other hooks and settings
  • Creates backup before modification
Validate Configurations

Check that all configured integrations are properly set up:

memorizer integrations health

Example Output:

Validating integrations...
  ✓ claude-code-hook: Valid (settings file exists, hooks configured)

Validates:

  • Configuration file exists and is readable
  • Integration-specific settings are properly formatted
  • Required commands are configured
Health Check

Comprehensive health check including both detection and validation:

memorizer integrations health

Example Output:

Framework Detection:
  ✓ claude-code-hook (installed at ~/.claude)

Configuration Validation:
  ✓ claude-code-hook: Valid (settings file exists, hooks configured)

Overall Status: Healthy (1/1 configured integrations valid)

Performs:

  • Framework installation detection
  • Configuration file validation
  • Integration setup verification
  • Overall health status summary

Usage

Background Daemon (Required)

The background daemon is the core of Agentic Memorizer. It maintains a precomputed index for quick startup, watching your memory directory and automatically updating the index as files change.

Quick Start
# Start the daemon (run in foreground - use Ctrl+C to stop)
memorizer daemon start

# OR set up as system service for automatic management (recommended):
memorizer daemon systemctl  # Linux
memorizer daemon launchctl  # macOS

Note: If you used initialize --integrations, the integration is already configured. Otherwise, configure your AI agent framework to call memorizer read (see Integration Setup section above).

Daemon Commands
# Start daemon (runs in foreground - press Ctrl+C to stop)
memorizer daemon start

# Check daemon status
memorizer daemon status

# Stop daemon
memorizer daemon stop

# Restart daemon
memorizer daemon restart

# Force immediate rebuild
memorizer daemon rebuild                    # Rebuild index
memorizer daemon rebuild --force            # Clear graph first, then rebuild
memorizer daemon rebuild --clear-stale      # Clear stale cache entries before rebuild

# View daemon logs
memorizer daemon logs              # Last 50 lines
memorizer daemon logs -f           # Follow logs
memorizer daemon logs -n 100       # Last 100 lines

# Hot-reload configuration without daemon restart
memorizer config reload
How It Works

The daemon:

  1. Watches your memory directory for file changes using fsnotify
  2. Processes files in parallel using a worker pool (3 workers by default)
  3. Rate limits API calls to respect Claude API limits (20/min default)
  4. Maintains a precomputed index in FalkorDB with all metadata and semantic analysis
  5. Updates the index automatically when files are added/modified/deleted
  6. Supports hot-reload of most configuration settings via config reload command

When you run memorizer read, it simply loads the precomputed index from FalkorDB instead of analyzing all files.

Daemon Configuration

In ~/.memorizer/config.yaml:

daemon:
  enabled: true                          # Enable daemon mode
  debounce_ms: 500                       # Debounce file events (milliseconds)
  workers: 3                             # Parallel worker count
  rate_limit_per_min: 20                 # API rate limit
  full_rebuild_interval_minutes: 60      # Periodic full rebuild interval
  http_port: 0                           # HTTP server for health + SSE (0 = disabled)
  log_file: ~/.memorizer/daemon.log
  log_level: info                        # debug, info, warn, error

Hot-Reloading: Most settings can be hot-reloaded using memorizer config reload without restarting the daemon:

  • ✓ daemon.workers, daemon.rate_limit_per_min, daemon.debounce_ms
  • ✓ daemon.full_rebuild_interval_minutes, daemon.http_port
  • ✓ analysis.* settings, claude.* settings
  • ✗ memory_root, analysis.cache_dir, daemon.log_file, mcp.log_file (require restart)
Running as a Service

For production use, run the daemon as a system service that starts automatically and restarts on failure. The application provides commands to generate service configuration files for systemd (Linux) and launchd (macOS).

Benefits of running as a service:

  • Automatic start on system boot or user login
  • Automatic restart if daemon crashes
  • Centralized log management
  • Health monitoring and status checking
  • No manual terminal session required
systemd (Linux)

Generate a systemd unit file:

memorizer daemon systemctl

This command outputs a complete systemd unit file. To install:

Option A: User Service (Recommended - No root required)

# Create directory
mkdir -p ~/.config/systemd/user

# Generate and save unit file
memorizer daemon systemctl > ~/.config/systemd/user/memorizer.service

# Reload systemd
systemctl --user daemon-reload

# Enable autostart
systemctl --user enable memorizer

# Start service
systemctl --user start memorizer

# Check status
systemctl --user status memorizer

# View logs
journalctl --user -u memorizer -f

Option B: System-Wide Service (Requires root)

# Generate and save unit file (requires sudo)
memorizer daemon systemctl | sudo tee /etc/systemd/system/memorizer.service

# Reload systemd
sudo systemctl daemon-reload

# Enable autostart
sudo systemctl enable memorizer

# Start service
sudo systemctl start memorizer

# Check status
systemctl status memorizer

# View logs
journalctl -u memorizer -f

Managing the service:

# Stop service
systemctl --user stop memorizer

# Restart service
systemctl --user restart memorizer

# Disable autostart
systemctl --user disable memorizer

# Remove service
systemctl --user stop memorizer
systemctl --user disable memorizer
rm ~/.config/systemd/user/memorizer.service
systemctl --user daemon-reload
launchd (macOS)

Generate a launchd property list:

memorizer daemon launchctl

This command outputs a complete launchd plist file. To install:

# Create directory
mkdir -p ~/Library/LaunchAgents

# Generate and save plist
memorizer daemon launchctl > ~/Library/LaunchAgents/com.$(whoami).memorizer.plist

# Load service
launchctl load ~/Library/LaunchAgents/com.$(whoami).memorizer.plist

# Start service (if not running)
launchctl start com.$(whoami).memorizer

# Check if running
launchctl list | grep memorizer

Managing the service:

# Stop service
launchctl stop com.$(whoami).memorizer

# Restart service
launchctl stop com.$(whoami).memorizer
launchctl start com.$(whoami).memorizer

# Disable autostart (unload)
launchctl unload ~/Library/LaunchAgents/com.$(whoami).memorizer.plist

# Remove service
launchctl unload ~/Library/LaunchAgents/com.$(whoami).memorizer.plist
rm ~/Library/LaunchAgents/com.$(whoami).memorizer.plist

View logs:

# Tail daemon log
tail -f ~/.memorizer/daemon.log

# Check Console.app for system messages (macOS)
open /Applications/Utilities/Console.app
Supervisor (Cross-Platform Alternative)

For development environments or servers without systemd, use Supervisor:

Install Supervisor:

# Ubuntu/Debian
sudo apt-get install supervisor

# macOS
brew install supervisor

# Or via pip
pip install supervisor

Configure:

Create /etc/supervisor/conf.d/memorizer.conf:

[program:memorizer]
command=/home/youruser/.local/bin/memorizer daemon start
directory=/home/youruser
autostart=true
autorestart=true
startretries=3
user=youruser
redirect_stderr=true
stdout_logfile=/var/log/memorizer/daemon.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=3
environment=HOME="/home/youruser"

Replace youruser with your username and adjust paths as needed.

Manage with supervisorctl:

# Reload config
sudo supervisorctl reread
sudo supervisorctl update

# Start service
sudo supervisorctl start memorizer

# Check status
sudo supervisorctl status memorizer

# Stop service
sudo supervisorctl stop memorizer

# Restart service
sudo supervisorctl restart memorizer

# View logs
sudo supervisorctl tail -f memorizer
Upgrading

When upgrading to a new version, the upgrade process depends on how you're running the daemon.

systemd (Linux):

# Stop service
systemctl --user stop memorizer

# Upgrade binary
go install github.com/leefowlercu/agentic-memorizer@latest
# OR: cd /path/to/repo && make install

# Start service
systemctl --user start memorizer

# Verify
systemctl --user status memorizer
memorizer version

Or use restart for one command:

# Stop and upgrade (Makefile handles daemon stop)
make install

# Restart service
systemctl --user restart memorizer

launchd (macOS):

# Stop service
launchctl stop com.$(whoami).memorizer

# Upgrade binary
go install github.com/leefowlercu/agentic-memorizer@latest
# OR: cd /path/to/repo && make install

# Start service
launchctl start com.$(whoami).memorizer

# Verify
launchctl list | grep memorizer
memorizer version

Supervisor:

# Stop service
sudo supervisorctl stop memorizer

# Upgrade binary
go install github.com/leefowlercu/agentic-memorizer@latest

# Start service
sudo supervisorctl start memorizer

# Verify
sudo supervisorctl status memorizer
Upgrading Manual Daemon

If running daemon manually (not as service):

# Stop daemon
memorizer daemon stop

# Upgrade
go install github.com/leefowlercu/agentic-memorizer@latest
# OR: cd /path/to/repo && make install

# Start daemon
memorizer daemon start

# Verify
memorizer version

Note: The Makefile install target automatically stops the daemon before replacing the binary:

# This command handles daemon shutdown automatically
make install
Service File Updates

Service files typically do not need to be regenerated when upgrading unless:

  • The binary path changed
  • New configuration options require service file changes
  • Release notes explicitly mention service file updates

Service files reference the binary by path, not version:

ExecStart=/home/user/.local/bin/memorizer daemon start

The service manager automatically uses whatever binary exists at that path after upgrade.

Why Service Managers Handle Upgrades Better

Manual daemon process:

  • ✗ Must manually stop before upgrade
  • ✗ Must manually restart after upgrade
  • ✗ On macOS, replacing running binary triggers security warnings
  • ✗ Old process may continue running from deleted inode

Service managers:

  • ✓ Orchestrated shutdown and restart
  • ✓ No security warnings
  • ✓ One-command upgrade with restart
  • ✓ Rollback capability if new version fails
  • ✓ Health monitoring during upgrade
Health Monitoring

Enable HTTP server for health checks and SSE notifications:

daemon:
  http_port: 8080

Then check health at: http://localhost:8080/health

Response includes uptime, files processed, API calls, errors, and build status.

Troubleshooting

Check daemon status:

./memorizer daemon status

Common issues:

  1. Daemon won't start - "daemon already running"

    • Check if daemon is actually running: ./memorizer daemon status
    • If not running but PID file exists: rm ~/.memorizer/daemon.pid
    • Try starting again

  2. Daemon crashes or exits immediately

    • Check logs: tail -f ~/.memorizer/daemon.log
    • Verify config file: cat ~/.memorizer/config.yaml
    • Ensure Claude API key is set (in config or ANTHROPIC_API_KEY env var)
    • Check file permissions on cache directory

  3. Index not updating after file changes

    • Verify daemon is running: ./memorizer daemon status
    • Check watcher is active in status output
    • Review daemon logs for file watcher errors
    • Ensure files aren't in skipped directories (.cache, .git)

  4. High API usage

    • Reduce workers: daemon.workers: 1 in config
    • Lower rate limit: daemon.rate_limit_per_min: 10
    • Increase rebuild interval: daemon.full_rebuild_interval_minutes: 120
    • Add files to skip list: analysis.skip_files in config

  5. Graph corruption after crash

    • FalkorDB persists data to ~/.memorizer/falkordb/
    • Force rebuild: ./memorizer daemon rebuild --force
    • If still corrupted: Clear graph data and rebuild: 
      memorizer daemon stop
rm -rf ~/.memorizer/falkordb/*
docker restart memorizer-falkordb
memorizer daemon start

  6. Service won't start (macOS/Linux)

    • macOS: Check Console.app for launchd errors
    • Linux: Check systemd logs: journalctl -u memorizer.service -n 50
    • Verify binary path in service config matches installation location
    • Check user permissions on config and cache directories

Debug logging:

daemon:
  log_level: debug
Adding Files to Memory

Simply add files to ~/.memorizer/memory/ (or the directory you've configured as the memory_root in config.yaml):

# Organize however you like
~/.memorizer/memory/
├── documents/
│   └── project-plan.md
├── presentations/
│   └── quarterly-review.pptx
└── images/
    └── architecture-diagram.png

On your next Claude Code session, these files will be automatically analyzed and indexed.

Using the MCP Server

The MCP (Model Context Protocol) server provides AI agents with tools, prompts, and resources to interact with your memory index. This section covers how to use the MCP server regardless of which AI agent framework you're using (Claude Code, Gemini CLI, Codex CLI, etc.).

The MCP server provides three types of capabilities: Tools for performing operations, Prompts for generating contextual messages, and Resources for accessing the memory index with real-time updates.

MCP Tools

The MCP server exposes five tools that AI agents can invoke to interact with your memory index:

1. search_files

Search for files using semantic search across filenames, summaries, tags, and topics.

Parameters:

  • query (required): Search query text
  • categories (optional): Array of categories to filter by (e.g., ["documents", "code"])
  • max_results (optional): Maximum results to return (default: 10, max: 100)

Example prompts that trigger this tool:

  • "Search my memory for files about authentication"
  • "Find documents related to API design"
  • "Show me code files that mention database migrations"
  • "What files do I have about FalkorDB?"

2. get_file_metadata

Retrieve complete metadata and semantic analysis for a specific file.

Parameters:

  • path (required): Absolute path to the file

Example prompts that trigger this tool:

  • "Show me details about ~/.memorizer/memory/docs/api-guide.md"
  • "What's in my architecture diagram file?"
  • "Get metadata for /Users/me/.memorizer/memory/notes.md"

3. list_recent_files

List recently modified files within a specified time period.

Parameters:

  • days (optional): Number of days to look back (default: 7, max: 365)
  • limit (optional): Maximum number of files (default: 20, max: 100)

Example prompts that trigger this tool:

  • "What files did I add this week?"
  • "Show me files modified in the last 3 days"
  • "List my recent documents"

4. get_related_files

Find files connected through shared tags, topics, or entities in the knowledge graph.

Parameters:

  • path (required): Path to the source file
  • limit (optional): Maximum related files to return (default: 10, max: 50)

Requirements: FalkorDB must be running

Example prompts that trigger this tool:

  • "What files are related to my API documentation?"
  • "Find files similar to ~/.memorizer/memory/architecture.md"
  • "Show me documents connected to this design proposal"

5. search_entities

Search for files that mention specific entities (technologies, people, concepts, organizations).

Parameters:

  • entity (required): Entity name to search for
  • entity_type (optional): Filter by type (technology, person, concept, organization)
  • max_results (optional): Maximum results (default: 10, max: 100)

Requirements: FalkorDB must be running

Example prompts that trigger this tool:

  • "Which files mention Terraform?"
  • "Find documents about authentication"
  • "Show me files that reference Docker"
  • "What mentions Go programming language?"
MCP Prompts

The MCP server provides three pre-configured prompt templates that generate contextual messages for analysis. These are currently available in Claude Code and may be supported by other MCP clients in the future.

1. analyze-file

Generates a detailed analysis request using the file's semantic metadata.

Arguments:

  • file_path (required): Path to the file to analyze
  • focus (optional): Specific aspect to focus on (e.g., "security", "performance", "architecture")

What it does: Creates a prompt that asks the AI to analyze the file's purpose, main concepts, relationships to other files, and notable patterns based on its semantic summary, tags, and topics.

Usage: If your MCP client supports prompts, select "analyze-file" from the prompt selector, provide the file path, and optionally specify a focus area like "security implications" or "architectural patterns".

2. search-context

Helps construct effective search queries by identifying related terms and strategies.

Arguments:

  • topic (required): Topic or concept to search for
  • category (optional): File category to focus on (e.g., "documents", "code")

What it does: Generates suggestions for key terms, related tags, file types to focus on, and alternative search terms based on the specified topic.

Usage: Use this prompt when you know what you're looking for conceptually but need help formulating an effective search query. Provide a topic like "API authentication" and get back ranked search strategies.

3. explain-summary

Generates a detailed explanation of how a file's semantic analysis was derived.

Arguments:

  • file_path (required): Path to the file whose summary to explain

What it does: Creates a prompt asking the AI to explain what the summary reveals about the file, how tags and topics were determined, the significance of the document type classification, and how to interpret the information.

Usage: Use this prompt when you want to understand why a file was analyzed and tagged in a particular way. Useful for validating or understanding the semantic analysis results.

MCP Resources

The MCP server exposes the memory index as three resources in different formats:

Available Resources:

  1. memorizer://index

    • Format: XML
    • MIME Type: application/xml
    • Description: Complete semantic index with hierarchical structure optimized for AI consumption

  2. memorizer://index/markdown

    • Format: Markdown
    • MIME Type: text/markdown
    • Description: Human-readable format with rich formatting and emojis

  3. memorizer://index/json

    • Format: JSON
    • MIME Type: application/json
    • Description: Structured data format for programmatic access

Reading Resources:

MCP clients can read these resources directly to access the full memory index. This is useful when you want complete context about all indexed files rather than querying specific files or searching.

Resource Subscriptions:

The MCP server supports resource subscriptions for real-time updates:

How it works:

  1. Subscribe: MCP client subscribes to one or more resource URIs (e.g., memorizer://index)
  2. Daemon Updates: When files are added, modified, or deleted, the daemon rebuilds the index
  3. SSE Notification: Daemon sends Server-Sent Event (SSE) to connected MCP servers
  4. Resource Updated: MCP server sends notifications/resources/updated to subscribed clients
  5. Client Refresh: AI agent automatically knows the index has changed and can re-fetch

Benefits:

  • AI agents stay synchronized with your latest files without manual refresh
  • Real-time awareness of newly added documents, images, or code
  • Automatic context updates during long-running sessions

Configuration:

The MCP server connects to the daemon's SSE endpoint automatically when daemon.http_port is configured:

daemon:
  http_port: 8080  # Enable HTTP API and SSE notifications

Subscription Workflow Example:

  1. AI agent starts and connects to MCP server
  2. Agent subscribes to memorizer://index/markdown resource
  3. You add a new document: ~/.memorizer/memory/new-design.md
  4. Daemon detects the file, analyzes it, rebuilds index
  5. Daemon sends SSE event: {"type": "index_updated", ...}
  6. MCP server receives event and checks subscriptions
  7. MCP server sends notification to agent: {"method": "notifications/resources/updated", "params": {"uri": "memorizer://index/markdown"}}
  8. Agent re-fetches the resource and now knows about new-design.md

This creates a seamless experience where your AI agent automatically becomes aware of new files as you add them to memory.

Manual Testing

View the precomputed index:

# Start daemon if not already running
memorizer daemon start

# In another terminal, read the index
memorizer read

This outputs the index (XML by default) that AI agents receive. The daemon must be running (or have completed at least one indexing cycle) for the index file to exist.

CLI Usage

Commands:

# Initialize config and memory directory
memorizer initialize [flags]

# Manage background daemon
memorizer daemon start
memorizer daemon stop
memorizer daemon status
memorizer daemon systemctl      # Generate systemd unit file
memorizer daemon launchctl      # Generate launchd plist

# Manage FalkorDB knowledge graph
memorizer graph start           # Start FalkorDB container
memorizer graph stop            # Stop FalkorDB container
memorizer graph status          # Check graph health and stats
memorizer daemon rebuild        # Rebuild index/graph (use --force to clear first)

# Manage semantic analysis cache
memorizer cache status          # Show cache statistics and version info
memorizer cache clear --stale   # Clear stale cache entries
memorizer cache clear --all     # Clear all cache entries

# Read precomputed index (for SessionStart hooks)
memorizer read [flags]

# Manage agent framework integrations
memorizer integrations list
memorizer integrations detect
memorizer integrations setup <integration-name>
memorizer integrations remove <integration-name>
memorizer integrations health
memorizer integrations health

# MCP server
memorizer mcp start

# Manage configuration
memorizer config validate
memorizer config reload
memorizer config show-schema

# Get help
memorizer --help
memorizer initialize --help
memorizer daemon --help
memorizer read --help
memorizer integrations --help
memorizer config --help

Common Flags:

# Read command flags
--format <xml|markdown|json>        # Output format
--integration <name>                # Format for specific integration (claude-code-hook, etc)

# Init command flags
--memory-root <dir>                 # Custom memory directory
--cache-dir <dir>                   # Custom cache directory
--force                             # Overwrite existing config
--integrations                # Configure agent framework integrations
--skip-integrations                 # Skip integration setup prompt
--http-port <port>                  # HTTP API port (0=disable, -1=interactive prompt)

Examples:

# Initialize (interactive prompts for API key, HTTP port, integrations)
memorizer initialize

# Initialize with HTTP API enabled on port 7600 (scripted, no prompt)
memorizer initialize --http-port 7600 --integrations

# Read index (XML format)
memorizer read

# Read index (Markdown format)
memorizer read --format markdown

# Read index (JSON format)
memorizer read --format json

# Read with Claude Code hook integration (SessionStart)
memorizer read --format xml --integration claude-code-hook

# Note: MCP integration uses tools, not read command

# Start daemon
memorizer daemon start

# Check daemon status
memorizer daemon status

# Force rebuild index
memorizer daemon rebuild

# List available integrations
memorizer integrations list

# Detect installed agent frameworks
memorizer integrations detect

# Setup Claude Code SessionStart hooks
memorizer integrations setup claude-code-hook

# Setup Claude Code MCP server
memorizer integrations setup claude-code-mcp

# Setup Gemini CLI SessionStart hooks
memorizer integrations setup gemini-cli-hook

# Setup Gemini CLI MCP server
memorizer integrations setup gemini-cli-mcp

# Remove integrations
memorizer integrations remove claude-code-hook
memorizer integrations remove claude-code-mcp
memorizer integrations remove gemini-cli-hook

# Validate integration configurations
memorizer integrations health
Controlling Semantic Analysis

Semantic analysis can be enabled or disabled in config.yaml:

analysis:
  enable: true  # Set to false to skip Claude API calls

When disabled, the daemon will only extract file metadata without semantic analysis.

Supported File Types

Directly Readable by Claude Code
  • Markdown (.md)
  • Text files (.txt)
  • Configuration files (.json, .yaml, .yml, .toml)
  • Images (.png, .jpg, .jpeg, .gif, .webp)
  • Code files (.go, .py, .js, .ts, .java, .c, .cpp, .rs, .rb, .php)
  • Transcripts (.vtt, .srt)
Requires Extraction
  • Word documents (.docx)
  • PowerPoint (.pptx)
  • PDFs (.pdf)

The index tells your AI agent which method to use for each file.

Configuration Options

The configuration system follows "convention over configuration" principles. Most settings have optimal defaults, so you only need to configure what you want to customize.

Configuration Tiers

User-Facing Settings (shown after initialize):

  • memory_root - Directory containing your memory files
  • claude.api_key - Anthropic API key (or set ANTHROPIC_API_KEY env var)
  • claude.model - Claude model to use (default: claude-sonnet-4-5-20250929)
  • daemon.http_port - HTTP API port for MCP integration (0 to disable)
  • daemon.log_level - Daemon log verbosity (debug/info/warn/error)
  • mcp.log_level - MCP server log verbosity
  • graph.host / graph.port - FalkorDB connection settings
  • graph.password - FalkorDB password (or set FALKORDB_PASSWORD env var)
  • embeddings.api_key - OpenAI API key for embeddings (or set OPENAI_API_KEY env var)

Advanced Settings (available but not in initialized config):

These settings have optimal defaults but can be customized by adding them to your config.yaml:

# Claude API tuning
claude:
  max_tokens: 1500           # Response length limit per analysis (1-8192)
  timeout: 30                # API request timeout in seconds (5-300)
  enable_vision: true        # Enable vision API for image analysis

# Analysis tuning
analysis:
  max_file_size: 10485760    # 10MB - files larger than this skip semantic analysis
  skip_extensions: [.zip, .tar, .gz, .exe, .bin, .dmg, .iso]
  skip_files: [memorizer]
  cache_dir: ~/.memorizer/.cache

# Daemon performance tuning
daemon:
  debounce_ms: 500           # Wait time before processing file changes
  workers: 3                 # Parallel processing workers
  rate_limit_per_min: 20     # Claude API rate limit
  full_rebuild_interval_minutes: 60
  log_file: ~/.memorizer/daemon.log

# MCP server settings
mcp:
  log_file: ~/.memorizer/mcp.log
  daemon_host: localhost
  daemon_port: 0             # Set to match daemon.http_port for MCP integration

# Embeddings tuning
embeddings:
  provider: openai           # Embedding provider (only 'openai' currently supported)
  model: text-embedding-3-small  # Embedding model
  dimensions: 1536           # Vector dimensions (must match model)

# Graph tuning
graph:
  similarity_threshold: 0.7  # Minimum similarity for related files (0.0-1.0)
  max_similar_files: 10      # Max similar files per query

To discover all available settings:

memorizer config show-schema --advanced-only

Derived Settings (computed automatically):

  • analysis.enabled - Automatically enabled when Claude API key is set
  • embeddings.enabled - Automatically enabled when OpenAI API key is set

See config.yaml.example for a complete reference with all available options

File Exclusions

The indexer automatically excludes:

  • Hidden files and directories (starting with .)
  • The .cache/ directory (where analyses are cached)
  • The memorizer binary itself (if located in the memory directory)

You can exclude additional files by name or extension in config.yaml:

analysis:
  skip_files:
    - memorizer  # Default
    - my-private-notes.md
    - temp-file.txt
  skip_extensions:
    - .log
    - .tmp
    - .bak
    - .swp

Files matching skip patterns are completely ignored during indexing and won't appear in the generated index.

Environment Variables
Configuration Override Pattern

All configuration settings can be overridden using environment variables with the MEMORIZER_ prefix. Configuration keys use dot notation (e.g., claude.model), which maps to environment variables by replacing dots with underscores and adding the prefix.

Examples:

# Override memory_root
export MEMORIZER_MEMORY_ROOT=/custom/memory/path

# Override claude.model
export MEMORIZER_CLAUDE_MODEL=claude-opus-4-5-20251101

# Override daemon.workers
export MEMORIZER_DAEMON_WORKERS=5

# Override daemon.http_port
export MEMORIZER_DAEMON_HTTP_PORT=8080

Priority: Environment variables take precedence over config.yaml settings.

Credential Environment Variables

API keys and passwords have dedicated environment variables that are checked before falling back to config file values:

ANTHROPIC_API_KEY

Claude API key for semantic analysis. If not set, falls back to claude.api_key in config.

export ANTHROPIC_API_KEY="your-claude-api-key"

OPENAI_API_KEY

OpenAI API key for vector embeddings (optional feature). If not set, falls back to embeddings.api_key in config.

export OPENAI_API_KEY="your-openai-api-key"

FALKORDB_PASSWORD

FalkorDB password for graph database authentication (optional). If not set, falls back to graph.password in config.

export FALKORDB_PASSWORD="your-falkordb-password"

Best Practice: Use these credential-specific environment variables instead of storing API keys in the config file.

MEMORIZER_APP_DIR

Customizes the application directory location. By default, configuration and data files are stored in ~/.memorizer/.

# Use a custom app directory
export MEMORIZER_APP_DIR=/path/to/custom/location
memorizer initialize

# Or for a single command
MEMORIZER_APP_DIR=/tmp/test-instance memorizer daemon start

Files stored in the app directory:

  • config.yaml - Configuration file
  • daemon.pid - Daemon process ID
  • daemon.log - Daemon logs (if configured)
  • mcp.log - MCP server logs (if configured)
  • falkordb/ - FalkorDB data persistence directory

Use cases:

  • Testing: Run isolated test instances without affecting your main instance
  • Multi-instance: Run multiple independent instances for different projects
  • Containers: Use custom paths in Docker or other containerized environments
  • CI/CD: Isolate build/test environments

Note: The memory directory and cache directory locations are controlled by config.yaml settings (or their corresponding MEMORIZER_MEMORY_ROOT and MEMORIZER_ANALYSIS_CACHE_DIR environment variables), not MEMORIZER_APP_DIR. Only the application's own files (config, PID, logs, FalkorDB data) use the app directory.

Output Formats

The memorizer supports three output formats:

XML (Default)

Highly structured XML following Anthropic's recommendations for Claude prompt engineering:

memorizer read
# or explicitly:
memorizer read --format xml
Markdown

Human-readable markdown, formatted for direct viewing:

memorizer read --format markdown
JSON Format

Pretty-printed JSON representation of the index:

memorizer read --format json
Integration-Specific Output

Use the --integration flag to format output for specific agent frameworks. This wraps the index in the appropriate structure for that framework:

# Claude Code hook integration (SessionStart injection)
memorizer read --format xml --integration claude-code-hook

# Gemini CLI hook integration (SessionStart injection)
memorizer read --format xml --integration gemini-cli-hook

# Can also use markdown or json formats
memorizer read --format markdown --integration claude-code-hook
memorizer read --format markdown --integration gemini-cli-hook

# Note: MCP integration doesn't use read - uses tools instead

Claude Code Integration Output Structure:

The Claude Code integration wraps the formatted index in a SessionStart hook JSON envelope:

{
  "continue": true,
  "suppressOutput": true,
  "systemMessage": "Memory index updated: 15 files (5 documents, 3 images, 2 presentations, 5 code files), 2.3 MB total — 12 cached, 3 analyzed",
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "<memory_index>...</memory_index>"
  }
}
  • continue: Always true - allows session to proceed
  • suppressOutput: Always true - keeps verbose index out of transcript
  • systemMessage: Concise summary visible to user in UI
  • hookSpecificOutput: Contains the full index (XML, Markdown, or JSON) in additionalContext, which Claude Code adds to the context window

More Info

Claude Hook JSON Common Fields

Claude SessionStart Hook Fields

Example Outputs

Here are examples of what the memory index looks like in each format:

XML Output Example

Abbreviated example showing structure (actual output includes all files):

<memory_index>
  <metadata>
    <generated>2025-10-05T14:30:22-04:00</generated>
    <file_count>3</file_count>
    <total_size_human>2.0 MB</total_size_human>
    <root_path>/Users/username/.agentic-memorizer/memory</root_path>
    <cache_stats>
      <cached_files>2</cached_files>
      <analyzed_files>1</analyzed_files>
    </cache_stats>
  </metadata>

  <recent_activity days="7">
    <file><path>documents/api-design-guide.md</path><modified>2025-10-04</modified></file>
  </recent_activity>

  <categories>
    <category name="documents" count="1" total_size="45.2 KB">
      <file>
        <name>api-design-guide.md</name>
        <path>/Users/username/.agentic-memorizer/memory/documents/api-design-guide.md</path>
        <modified>2025-10-04</modified>
        <size_human>45.2 KB</size_human>
        <file_type>markdown</file_type>
        <readable>true</readable>
        <metadata>
          <word_count>4520</word_count>
          <sections>
            <section>Introduction</section>
            <section>RESTful Principles</section>
            <section>Versioning Strategies</section>
            <section>Authentication</section>
            <section>Error Handling</section>
            <section>Rate Limiting</section>
            <section>Documentation</section>
            <section>Best Practices</section>
          </sections>
        </metadata>
        <semantic>
          <summary>Comprehensive API design guidelines covering RESTful principles, versioning strategies, authentication patterns, and best practices for building scalable microservices.</summary>
          <document_type>technical-guide</document_type>
          <topics>
            <topic>RESTful API design principles and conventions</topic>
            <topic>API versioning and backward compatibility</topic>
            <!-- Additional topics -->
          </topics>
          <tags>
            <tag>api-design</tag>
            <tag>rest</tag>
            <tag>microservices</tag>
          </tags>
        </semantic>
      </file>
      <!-- Additional files in this category -->
    </category>
    <!-- Additional categories: code, images, presentations, etc. -->
  </categories>

  <usage_guide>
    <direct_read_extensions>md, txt, json, yaml, vtt, go, py, js, ts, png, jpg</direct_read_extensions>
    <direct_read_tool>Read tool</direct_read_tool>
    <extraction_required_extensions>docx, pptx, pdf</extraction_required_extensions>
    <extraction_required_tool>Bash + conversion tools</extraction_required_tool>
  </usage_guide>
</memory_index>
Markdown Output Example

Abbreviated example showing structure (actual output includes all files):

# Claude Code Agentic Memory Index
📅 Generated: 2025-10-05 14:30:24
📁 Files: 3 | 💾 Total Size: 2.0 MB
📂 Root: /Users/username/.agentic-memorizer/memory

## 🕐 Recent Activity (Last 7 Days)
- 2025-10-04: `documents/api-design-guide.md`

---

## 📄 Documents (1 files, 45.2 KB)

### api-design-guide.md
**Path**: `/Users/username/.agentic-memorizer/memory/documents/api-design-guide.md`
**Modified**: 2025-10-04 | **Size**: 45.2 KB | **Words**: 4,520
**Sections**: Introduction • RESTful Principles • Versioning Strategies • Authentication • Error Handling • Rate Limiting • Documentation • Best Practices
**Type**: Markdown • Technical-Guide

**Summary**: Comprehensive API design guidelines covering RESTful principles, versioning strategies, authentication patterns, and best practices for building scalable microservices.

**Topics**: RESTful API design principles, API versioning, Authentication patterns, Rate limiting
**Tags**: `api-design` `rest` `microservices` `best-practices`

✓ Use Read tool directly

## 💻 Code (1 files, 12.8 KB)
[... similar structure for code files ...]

## 🖼️ Images (1 files, 1.4 MB)
[... similar structure for images ...]

## Usage Guide
**Reading Files**:
- ✅ **Direct**: Markdown, text, VTT, JSON, YAML, images, code → Use Read tool
- ⚠️ **Extraction needed**: DOCX, PPTX, PDF → Use Bash + conversion tools

Development

Project Structure
agentic-memorizer/
├── main.go                   # Main entry point
├── LICENSE                   # MIT License
├── .goreleaser.yaml          # GoReleaser configuration for multi-platform releases
├── docker-compose.yml        # FalkorDB Docker configuration
├── cmd/
│   ├── root.go               # Root command
│   ├── initialize/           # Initialization command
│   │   └── initialize.go
│   ├── daemon/               # Daemon management commands
│   │   ├── daemon.go         # Parent daemon command
│   │   └── subcommands/      # Daemon subcommands (8 total)
│   │       ├── start.go
│   │       ├── stop.go
│   │       ├── status.go
│   │       ├── restart.go
│   │       ├── rebuild.go
│   │       ├── logs.go
│   │       ├── systemctl.go  # Generate systemd unit files
│   │       └── launchctl.go  # Generate launchd plist files
│   ├── graph/                # FalkorDB graph management commands
│   │   ├── graph.go          # Parent graph command
│   │   └── subcommands/      # Graph subcommands (3 total)
│   │       ├── start.go      # Start FalkorDB container
│   │       ├── stop.go       # Stop FalkorDB container
│   │       └── status.go     # Check graph health
│   ├── cache/                # Cache management commands
│   │   ├── cache.go          # Parent cache command
│   │   └── subcommands/      # Cache subcommands (2 total)
│   │       ├── status.go     # Show cache statistics
│   │       └── clear.go      # Clear cache entries
│   ├── mcp/                  # MCP server commands
│   │   ├── mcp.go            # Parent mcp command
│   │   └── subcommands/
│   │       └── start.go      # Start MCP server
│   ├── integrations/         # Integration management commands
│   │   ├── integrations.go   # Parent integrations command
│   │   └── subcommands/      # Integration subcommands (6 total)
│   │       ├── list.go
│   │       ├── detect.go
│   │       ├── setup.go
│   │       ├── remove.go
│   │       ├── health.go     # Health check and validation
│   │       └── helpers.go
│   ├── config/               # Configuration commands
│   │   ├── config.go         # Parent config command
│   │   └── subcommands/      # Config subcommands (3 total)
│   │       ├── validate.go
│   │       ├── reload.go
│   │       └── show_schema.go
│   ├── read/                 # Read precomputed index
│   │   └── read.go
│   └── version/              # Version command
│       └── version.go
├── internal/
│   ├── config/               # Configuration loading, validation, and hot-reload
│   ├── daemon/               # Background daemon implementation
│   │   ├── api/              # HTTP API server, handlers, SSE
│   │   └── worker/           # Worker pool for file processing
│   ├── graph/                # FalkorDB knowledge graph
│   │   ├── client.go         # FalkorDB connection management
│   │   ├── manager.go        # Graph operations (CRUD, search)
│   │   ├── queries.go        # Cypher query patterns
│   │   ├── schema.go         # Node/edge types and constraints
│   │   └── export.go         # Graph to index export
│   ├── embeddings/           # Vector embeddings (optional)
│   ├── watcher/              # File system watching (fsnotify)
│   ├── walker/               # File system traversal with filtering
│   ├── metadata/             # File metadata extraction (9 category handlers)
│   ├── semantic/             # Claude API integration for semantic analysis
│   ├── cache/                # Content-addressable analysis caching
│   ├── search/               # Semantic search engine (graph-powered)
│   ├── format/               # Output formatting system
│   │   ├── formatters/       # Individual formatters (text, JSON, XML, YAML, markdown)
│   │   └── testdata/         # Test data for formatters
│   ├── mcp/                  # MCP server implementation
│   │   ├── protocol/         # JSON-RPC 2.0 protocol messages
│   │   └── transport/        # Stdio transport layer
│   ├── integrations/         # Integration framework and adapters
│   │   └── adapters/         # Framework-specific adapters
│   │       ├── claude/       # Hook and MCP adapters for Claude Code
│   │       ├── gemini/       # Hook and MCP adapters for Gemini CLI
│   │       └── codex/        # MCP adapter for Codex CLI
│   ├── docker/               # Docker container management utilities
│   ├── servicemanager/       # Service manager integration (systemd, launchd)
│   ├── tui/                  # Terminal UI components
│   │   ├── initialize/       # Initialization wizard
│   │   └── styles/           # TUI styling
│   └── version/              # Version information and embedding
│       ├── VERSION           # Semantic version file (embedded)
│       └── version.go        # Version getters with buildinfo fallback
├── scripts/                  # Release automation scripts
│   ├── bump-version.sh       # Semantic version bumping
│   └── prepare-release.sh    # Release preparation and automation
├── pkg/types/                # Shared types and data structures
├── docs/                     # Documentation
│   ├── subsystems/           # Comprehensive subsystem documentation
│   ├── migration/            # Migration guides
│   └── wip/                  # Work in progress documentation
├── e2e/                      # End-to-end testing framework
│   ├── harness/              # Test harness and utilities
│   ├── tests/                # Test suites
│   ├── fixtures/             # Test fixtures and data
│   ├── scripts/              # Test automation scripts
│   ├── docker-compose.yml    # Test environment setup
│   └── Dockerfile.test       # Test container image
└── testdata/                 # Unit test files
Building and Testing
# Building
make build             # Build binary with version info from git
make install           # Build and install to ~/.local/bin

# Testing
make test              # Run unit tests only (fast, no external dependencies)
make test-integration  # Run integration tests only (requires daemon, slower)
make test-all          # Run all tests (unit + integration)
make test-race         # Run tests with race detector (important for concurrent code)
make coverage          # Generate coverage report
make coverage-html     # Generate and view HTML coverage report

# Code Quality
make fmt               # Format code with gofmt
make vet               # Run go vet
make lint              # Run golangci-lint (if installed)
make check             # Run all checks (fmt, vet, test-all)

# Utilities
make clean             # Remove build artifacts
make clean-cache       # Remove cache files only
make deps              # Update dependencies

Test Types:

  • Unit tests (make test) - Fast, no external dependencies
  • Integration tests (make test-integration) - Full daemon lifecycle, requires -tags=integration
  • E2E tests (make test-e2e) - Complete workflows with Docker-based FalkorDB
  • Integration tests use MEMORIZER_APP_DIR for isolated environments
  • Test data in testdata/ directory
End-to-End Testing

The project includes comprehensive E2E tests covering complete workflows across all major subsystems:

# Run all E2E tests (requires Docker for FalkorDB)
make test-e2e

# Run specific E2E test suite
go test -tags=e2e -v ./e2e/tests/ -run TestCLI        # CLI commands
go test -tags=e2e -v ./e2e/tests/ -run TestDaemon     # Daemon lifecycle
go test -tags=e2e -v ./e2e/tests/ -run TestHTTPAPI    # HTTP endpoints
go test -tags=e2e -v ./e2e/tests/ -run TestMCP        # MCP server
go test -tags=e2e -v ./e2e/tests/ -run TestGraph      # FalkorDB operations

E2E Test Coverage:

  • CLI Tests - All 30 commands with argument parsing and output validation
  • Daemon Tests - Start, stop, status, restart, rebuild operations
  • Filesystem Tests - File watching, processing pipelines, cache behavior
  • HTTP API Tests - All 9 REST endpoints with request/response validation
  • SSE Tests - Real-time event delivery and connection management
  • Configuration Tests - Loading, validation, hot-reload, error handling
  • Graph Tests - FalkorDB CRUD, schema, queries, and graceful degradation
  • Integration Tests - All framework adapters (Claude Code, Gemini, Codex, etc.)
  • Output Format Tests - XML, JSON, Markdown processors with schema validation
  • Walker Tests - Directory/file/extension skip patterns

The test harness (e2e/harness/) provides isolated environments, daemon management, and automatic cleanup. See docs/subsystems/e2e-tests/ for architecture details.

Adding New File Type Handlers
  1. Create handler in internal/metadata/
  2. Implement FileHandler interface: 
    type FileHandler interface {
    Extract(path string, info os.FileInfo) (*types.FileMetadata, error)
    CanHandle(ext string) bool
}
  3. Register in internal/metadata/extractor.go

See existing handlers for examples.

Limitations & Known Issues

Current Limitations

  • API Costs: Semantic analysis uses Claude API calls (costs apply)

    • Mitigated by caching (only analyzes new/modified files)
    • Can disable semantic analysis in config: analysis.enabled: false for metadata-only mode

  • File Size Limit: Default 10MB max for semantic analysis

    • Configurable via analysis.max_file_size in config
    • Larger files are indexed with metadata only

  • Internet Required: Needs connection for Claude API calls

    • Cached analyses work offline
    • Metadata extraction works offline

  • File Format Support: Limited to formats with extractors

    • Common formats covered (docs, images, code, etc.)
    • Binary files without extractors get basic metadata only
Known Issues
  • Some PPTX files with complex formatting may have incomplete extraction
  • PDF page count detection is basic (stub implementation)
  • Very large directories (1000+ files) may take time on first run

Troubleshooting

"API key is required" error

Set your API key in config or environment:

export ANTHROPIC_API_KEY="your-key-here"
Index not appearing in AI agent
  1. Verify daemon is running: memorizer daemon status
  2. Check your framework's integration configuration:
    • Claude Code: Check ~/.claude/settings.json has SessionStart hooks configured
    • Other frameworks: Verify you followed the setup instructions from memorizer integrations setup <framework-name>
  3. Verify binary path is correct (~/.local/bin/memorizer or ~/go/bin/memorizer)
  4. Test manually: memorizer read
  5. Check your AI agent's output/logs for errors
Config reload not applying changes
  1. Some settings require daemon restart (see Daemon Configuration section)
  2. Validate config syntax: memorizer config validate
  3. Check daemon logs: tail -f ~/.memorizer/daemon.log
  4. If reload fails, restart: memorizer daemon restart
Reducing resource usage

When indexing many files:

  • Reduce daemon workers: daemon.workers: 1 in config
  • Lower rate limit: daemon.rate_limit_per_min: 10 in config
  • Disable semantic analysis temporarily: analysis.enabled: false in config
Cache issues

The semantic analysis cache uses versioning to detect stale entries after application upgrades.

Check cache status:

memorizer cache status

This shows:

  • Current cache version
  • Total entries and size
  • Version distribution (current, legacy, stale)
  • Number of entries that need re-analysis

Clear stale entries (recommended after upgrade):

# Clear only stale/legacy entries
memorizer cache clear --stale

# Or include with rebuild
memorizer daemon rebuild --clear-stale

Force re-analysis of all files:

# Clear all cache entries
memorizer cache clear --all
memorizer daemon restart

Legacy entries (v0.0.0): Entries from before cache versioning was implemented. They will be re-analyzed automatically on next daemon rebuild.

Graph data issues

If you need to reset the knowledge graph (e.g., seeing stale data, want to start fresh):

Clear graph data:

# Stop daemon first
memorizer daemon stop

# Delete persistence files
rm -rf ~/.memorizer/falkordb/*

# Restart FalkorDB container
docker restart memorizer-falkordb

# Start daemon (will rebuild from memory files)
memorizer daemon start

Verify graph was cleared:

memorizer graph status

This shows node/relationship counts. After clearing, you should see 5 nodes (category nodes) and 0 files.

Contributing

Contributions are welcome! To contribute:

  1. Report Issues: Open an issue on GitHub describing the problem
  2. Suggest Features: Propose new features via GitHub issues
  3. Submit Pull Requests: Fork the repo, make changes, and submit a PR
  4. Follow Standards: Use Go conventions, add tests, update docs

See existing code for examples and patterns.

License

MIT License - see LICENSE file for details.

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cache
cache/subcommands
config
config/subcommands
daemon
daemon/subcommands
graph
graph/subcommands
initialize
integrations
integrations/subcommands
mcp
mcp/subcommands
read
version
e2e
fixtures/memory command
harness
internal
cache
Package cache provides semantic analysis caching with content-addressable storage.
 Package cache provides semantic analysis caching with content-addressable storage.
config
daemon
daemon/api
daemon/worker
docker
embeddings
format
Package format provides centralized CLI output formatting for agentic-memorizer.
 Package format provides centralized CLI output formatting for agentic-memorizer.
format/formatters
graph
integrations
integrations/adapters/claude
integrations/adapters/codex
integrations/adapters/gemini
mcp
mcp/protocol
mcp/transport
metadata
search
semantic
servicemanager
tui/initialize
tui/initialize/components
tui/initialize/steps
tui/styles
version
walker
watcher
pkg
types
Package types defines data structures used throughout agentic-memorizer.
 Package types defines data structures used throughout agentic-memorizer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.