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
curl -X POST http://127.0.0.1:4200/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "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

Session Compaction

Auto Compaction

Automatic compaction when session message count reaches threshold:

[compaction]
threshold = 80
keep_recent = 20
max_summary_tokens = 1024

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

Memory Operations

Endpoint	Method	Description
`/api/memory`	GET	Search memory
`/api/memory`	POST	Store memory
`/api/memory/{id}`	GET	Get memory
`/api/memory/{id}`	DELETE	Delete memory

Session Operations

Endpoint	Method	Description
`/api/memory/sessions`	GET	List sessions
`/api/memory/sessions/{id}`	GET	Get session
`/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

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>