Memory System

LibreFang's memory system provides persistent storage, semantic search, and knowledge graph functionality.

Overview

The LibreFang memory system includes:

SQLite Persistence - Structured KV storage
Vector Embeddings - Semantic search capability
Knowledge Graph - Entities and relationships
Session Management - Cross-channel memory
Usage Tracking - Cost and usage statistics

Tip: Memory data is stored in ~/.librefang/data/librefang.db by default, with configurable storage path.

Architecture

┌─────────────────────────────────────────┐
│              Agent Loop                  │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│           Memory Subsystem               │
├─────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  │
│  │ Session │  │ Vector  │  │Knowledge│  │
│  │ Store   │  │ Search  │  │ Graph   │  │
│  └─────────┘  └─────────┘  └─────────┘  │
├─────────────────────────────────────────┤
│           SQLite Database               │
└─────────────────────────────────────────┘

Configuration

Basic Configuration

[memory]
decay_rate = 0.05
sqlite_path = "~/.librefang/data/librefang.db"

Advanced Configuration

[memory]
decay_rate = 0.05
sqlite_path = "~/.librefang/data/librefang.db"
vector_dimension = 1536
max_memory_items = 10000
auto_compact = true

Field	Type	Default	Description
`decay_rate`	Float	0.05	Memory confidence decay rate
`sqlite_path`	String	~/.librefang/data/librefang.db	Database path
`vector_dimension`	Integer	1536	Vector dimension
`max_memory_items`	Integer	10000	Maximum memory entries
`auto_compact`	Boolean	true	Auto compaction

Session Management

Create Session

# Create new session
librefang session create --name "research-project"

List Sessions

# List all sessions
librefang session list

Session Operations

# View session details
librefang session info <session-id>

# Delete session
librefang session delete <session-id>

# Compact session
librefang session compact <session-id>

# Export session
librefang session export <session-id> --format json

Memory Operations

Store Memory

# Store simple memory
librefang memory store --key "user:preference:theme" --value "dark"

# Store structured data
librefang memory store --key "project:details" --data '{"name": "LibreFang", "version": "1.0"}'

# Store with tags
librefang memory store --key "note:1" --value "Important note" --tags "work,urgent"

Search Memory

# Keyword search
librefang memory search "project"

# Vector search (semantic search)
librefang memory search --vector "find information about AI agents"

# Search with filters
librefang memory search "meeting" --tags "work" --limit 10

Memory Operations

# Read memory
librefang memory get <key>

# Update memory
librefang memory update <key> --value "new value"

# Delete memory
librefang memory delete <key>

# List all memories
librefang memory list --prefix "project:"

Vector Search

Semantic Search

LibreFang supports semantic search with vector embeddings:

# Semantic search example
librefang memory search --vector "machine learning techniques for text classification"

Similarity Threshold

[memory]
similarity_threshold = 0.75

API Endpoint

# Semantic search API (GET with query params)
curl "http://127.0.0.1:4545/api/memory/search?q=find+information+about+AI&limit=10&threshold=0.8"

Knowledge Graph

Entity Management

# Add entity
librefang kg add-entity --type "person" --name "John Doe" --properties '{"role": "developer"}'

# List entities
librefang kg list-entities --type "person"

# Search entities
librefang kg search-entities "John"

Relationship Management

# Add relationship
librefang kg add-relation \
  --from "person:john" \
  --relation "works_at" \
  --to "company:acme"

# List relationships
librefang kg list-relations --entity "person:john"

# Query relationships
librefang kg query --from "person:john" --relation "works_at"

Graph Queries

# Query path
librefang kg path --from "person:alice" --to "company:acme"

# Query subgraph
librefang kg subgraph --entity "person:bob" --depth 2

Automatic compaction when session message count reaches threshold. Compaction settings are managed internally by the runtime and are not exposed in config.toml. The default threshold is 80 messages, keeping the 20 most recent verbatim and summarizing the rest.

Manual Compaction

# Compact session
librefang session compact <session-id>

# Compact all sessions
librefang session compact-all

# View compaction status
librefang session compaction-status

Compaction Algorithm

Keep Recent N Messages
Extract Key Information
Generate Summary
Keep Tool Call History

Usage Tracking

View Usage

# View usage statistics
librefang usage

# View Agent usage
librefang usage --agent <agent-id>

# View provider usage
librefang usage --provider

Cost Tracking

# View costs
librefang cost

# View costs by date range
librefang cost --from 2025-01-01 --to 2025-01-31

# Export report
librefang cost export --format csv

API Endpoints

KV Memory Operations

Endpoint	Method	Description
`/api/memory/search`	GET	Search memory (query params: `q`, `limit`, `threshold`)
`/api/memory`	POST	Store a memory entry
`/api/memory/{id}`	GET	Get a specific memory entry
`/api/memory/{id}`	DELETE	Delete a memory entry

Session Operations

Endpoint	Method	Description
`/api/memory/sessions`	GET	List sessions
`/api/memory/sessions/{id}`	GET	Get session details
`/api/memory/sessions/{id}/compact`	POST	Compact session

Knowledge Graph

Endpoint	Method	Description
`/api/memory/kg/entities`	GET	List entities
`/api/memory/kg/relations`	GET	List relations
`/api/memory/kg/query`	POST	Query graph

Proactive Memory

Proactive memory allows agents to autonomously surface, consolidate, and recall long-term knowledge without explicit tool calls.

Endpoint	Method	Description
`/api/memory/proactive`	GET	List all proactive memory entries
`/api/memory/proactive`	POST	Create a proactive memory entry
`/api/memory/proactive/{id}`	GET	Get a proactive memory entry
`/api/memory/proactive/{id}`	DELETE	Delete a proactive memory entry
`/api/memory/proactive/search`	GET	Semantic search over proactive memories
`/api/memory/proactive/consolidate`	POST	Trigger consolidation of recent memories

Best Practices

Regular Compaction - Prevent sessions from growing too large
Use Tags - Easy organization and search
Set Decay Rate - Control memory confidence
Monitor Usage - Track costs and usage

Troubleshooting

Slow Memory Search

# Rebuild vector index
librefang memory reindex

# Check index status
librefang memory index-status

Database Bloat

# Clean old data
librefang memory cleanup --older-than 30d

# Vacuum database
librefang memory vacuum

Memory Loss

# Check database integrity
librefang doctor

# Restore backup
librefang memory restore --backup <path>

Memory System

Overview

Architecture

Configuration

Basic Configuration

Advanced Configuration

Session Management

Create Session

List Sessions

Session Operations

Memory Operations

Store Memory

Search Memory

Memory Operations

Vector Search

Semantic Search

Similarity Threshold

API Endpoint

Knowledge Graph

Entity Management

Relationship Management

Graph Queries

Session Compaction

Auto Compaction

Manual Compaction

Compaction Algorithm

Usage Tracking

View Usage

Cost Tracking

API Endpoints

KV Memory Operations

Session Operations

Knowledge Graph

Proactive Memory

Best Practices

Troubleshooting

Slow Memory Search

Database Bloat

Memory Loss