Agent Journal

Agent Journal - Session Search, Knowledge Bank & Content Indexing

Search and retrieve past AI agent sessions, stored knowledge, and indexed content.

When to Use

• User asks "have I done this before?" or "find previous work on X"
• User wants context from past sessions about a topic
• User needs to find how a problem was solved previously
• User wants to export or reference a past conversation
• Agent learns a convention or best practice that should be remembered
• User wants to recall project-specific knowledge
• User wants to index and search documentation or specs

Commands

Search Sessions

# Hybrid search (combines keyword + semantic, best quality)
agent-journal search "<query>" --mode hybrid --max 10

# Semantic search (best for concepts and "how to" queries)
agent-journal search "<query>" --mode semantic --max 10

# Lexical search (fast keyword search)
agent-journal search "<query>" --mode lexical --max 10

# Get context around matches (N messages before/after)
agent-journal search "<query>" --context 5

# Filter by project
agent-journal search "<query>" --project <project-name>

# Filter by agent
agent-journal search "<query>" --agent claude-code
agent-journal search "<query>" --agent copilot-cli

# JSON output for parsing
agent-journal search "<query>" --robot

Index Sessions

# Rebuild index (run after new sessions)
agent-journal index --rebuild

# Quick incremental index
agent-journal index

# Watch mode (continuous indexing)
agent-journal index --watch

Export Session

# Export to markdown
agent-journal export <session-id> --format md

# Export to HTML
agent-journal export <session-id> --format html

# Output to stdout
agent-journal export <session-id> --stdout

Check Status

# Show configuration and paths
agent-journal config show

# List embedding models
agent-journal models list

Search Mode Selection

Knowledge Bank Commands

Remember - Store Knowledge

# Store a fact or convention
agent-journal remember "Use ESLint Airbnb config for TypeScript" --tags "code-style,linting"

# Store project-specific knowledge
agent-journal remember "API uses JWT with 24h expiry" --project my-api --tags "auth,security"

# Include source reference
agent-journal remember "Pattern from auth refactoring" --source "session:abc123"

Recall - Search Knowledge

# Search knowledge bank
agent-journal recall "authentication" --mode hybrid

# Filter by tags
agent-journal recall "code style" --tags "linting"

# Filter by project
agent-journal recall "conventions" --project my-api

# JSON output
agent-journal recall "security" --robot

Reinforce - Keep Knowledge Fresh

# Reset decay timer when knowledge was useful
agent-journal reinforce <id>

# Reinforce multiple entries
agent-journal reinforce abc123 def456

Forget - Remove Knowledge

# Remove by ID
agent-journal forget abc123

Content Indexing Commands

Index and search markdown files, specs, and documentation.

Index Content from Directory

# Index all markdown files in a directory
agent-journal content index ./docs --project my-project

# Index with custom filter
agent-journal content index ./specs --filter "*.md" --project api-specs

# Non-recursive indexing
agent-journal content index ./docs --recursive false

# Rebuild content index
agent-journal content index ./docs --rebuild

Add Content Directly

# Add content with source identifier (for later lookup)
agent-journal content add --source "design/auth-flow" --title "Auth Flow Design" --content "..."

# Add with project and tags
agent-journal content add --source "notes/api-v2" --title "API v2 Notes" \
  --project my-api --tags "api,design"

# Pipe content from file
cat design.md | agent-journal content add --source "design/main" --title "Design Doc"

Search Content

# Search indexed content
agent-journal content search "authentication flow"

# Filter by project
agent-journal content search "api design" --project my-api

# Filter by source prefix (directory/location)
agent-journal content search "endpoints" --source-prefix "docs/api/"

# Filter by tags
agent-journal content search "security" --tags "auth,security"

# Limit results
agent-journal content search "database" --max 5

# JSON output
agent-journal content search "config" --robot

List Content

# List all indexed content
agent-journal content list

# Filter by project
agent-journal content list --project my-api

# Filter by source prefix
agent-journal content list --source-prefix "specs/"

# Show only expired content
agent-journal content list --expired

# JSON output
agent-journal content list --robot

Remove Content

# Remove by exact source
agent-journal content remove --source "docs/old-spec.md"

# Remove by source prefix (all under directory)
agent-journal content remove --source-prefix "docs/deprecated/"

# Remove by project
agent-journal content remove --project old-project

# Remove by ID
agent-journal content remove --id abc123

# Force (skip confirmation)
agent-journal content remove --project old-project --force

Reinforce Content

# Reset decay timer for important content
agent-journal content reinforce --source "docs/api-spec.md"

Knowledge Decay System

All knowledge and content entries decay over time with a 90-day half-life:

• Fresh (>75%): Recently added or reinforced
• Good (50-75%): Still relevant
• Aging (25-50%): Consider reinforcing
• Decaying (<25%): Will expire soon ⚠️

Reinforce entries when they're useful to keep them fresh.

MCP Server Mode

# Start MCP server for AI agent integration
agent-journal mcp

MCP Tools Available

Example Workflows

Find previous solution

agent-journal search "fix authentication error" --mode semantic --context 3 --max 5

Index project documentation

agent-journal content index ./docs --project my-project
agent-journal content search "api endpoints" --project my-project

Store and recall conventions

agent-journal remember "Use snake_case for database columns" --project my-api --tags "conventions,db"
agent-journal recall "database conventions" --project my-api

Export for documentation

agent-journal search "implemented feature X" --mode semantic --max 1
agent-journal export <session-id> --format md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.