DocsMemory

Memory System

Give your agents persistent memory using markdown-based storage.

Quick Start

quickstart.py

from connectonion import Agent, Memory

memory = Memory()
agent = Agent(
    name="assistant",
    system_prompt="You are a helpful assistant with memory.",
    tools=[memory]
)

# Agent can now remember things
agent.input("Remember that Alice prefers email communication")
agent.input("What do I know about Alice?")

What is Memory?

Memory is a simple, file-based storage system that lets your agents:

Persistent Storage

Save information across sessions

Key-Value Retrieval

Retrieve information by specific keys

Regex Search

Search across all memories with patterns

Markdown Format

Organize knowledge in human-readable format

Storage Strategy

Memories start in a single memory.md file. When the file exceeds 3000 lines, it automatically splits into a directory structure with separate .md files per memory key.

Installation

Memory is included in ConnectOnion:

Terminal

$pip install connectonion

Basic Usage

Creating a Memory Instance

init_memory.py

from connectonion import Memory

# Default (creates memory.md)
memory = Memory()

# Custom file path
memory = Memory(memory_file="agent_knowledge.md")

# Legacy: directory structure (creates directory immediately)
memory = Memory(memory_dir="agent_knowledge")

Adding Memory to an Agent

agent_with_memory.py

from connectonion import Agent, Memory

memory = Memory()
agent = Agent("assistant", tools=[memory])

Now your agent has access to 4 memory methods:

write_memory(key, content)- Save or update information
read_memory(key)- Retrieve information
list_memories()- Show all stored memories
search_memory(pattern)- Search with regex

Memory Methods

write_memory

Save information to memory:

write.py

memory.write_memory("alice-notes", "Alice prefers email\nAlice works at TechCorp")
# Returns: "Memory saved: alice-notes"

Keys are sanitized: Only alphanumeric, hyphens, and underscores allowed. Converted to lowercase.

read_memory

Retrieve saved information:

read.py

memory.read_memory("alice-notes")
# Returns:
# Memory: alice-notes
#
# Alice prefers email
# Alice works at TechCorp

list_memories

Show all stored memories:

list.py

memory.list_memories()
# Returns:
# Stored Memories (3):
# 1. alice-notes (85 bytes)
# 2. bob-notes (62 bytes)
# 3. project-x (120 bytes)

search_memory

Search across all memories using regex:

search.py

# Simple text search (case-sensitive by default)
memory.search_memory("email")

# Case-insensitive search with (?i) flag
memory.search_memory("(?i)email")

# Regex patterns
memory.search_memory(r"\w+@\w+\.\w+")  # Find email addresses
memory.search_memory(r"Project [A-Z]")  # Find project names

Examples

Example 1: Customer Notes

customer_notes.py

from connectonion import Agent, Memory

memory = Memory(memory_dir="customer_notes")
agent = Agent(
    name="sales-assistant",
    system_prompt="You help track customer information.",
    tools=[memory]
)

# Save customer info
agent.input("Remember that Alice from TechCorp is interested in our API product and prefers email contact")

# Later, recall the information
agent.input("What do I know about Alice?")
# Agent will use read_memory() to retrieve Alice's info

Example 2: Project Tracker

project_tracker.py

from connectonion import Agent, Memory

memory = Memory(memory_dir="projects")
agent = Agent(
    name="project-manager",
    system_prompt="You track project status and notes.",
    tools=[memory]
)

# Save project updates
agent.input("Remember: Project Alpha is 80% complete, needs final testing")
agent.input("Remember: Project Beta is blocked, waiting on API keys")

# Search for blocked projects
agent.input("Which projects are blocked?")
# Agent will use search_memory("blocked") to find relevant projects

Example 3: Research Assistant

research_assistant.py

from connectonion import Agent, Memory

def web_search(query: str) -> str:
    """Search the web for information."""
    # Your search implementation
    return f"Results for {query}"

memory = Memory(memory_dir="research")
agent = Agent(
    name="researcher",
    system_prompt="You research topics and save key findings.",
    tools=[web_search, memory]
)

# Research and save
agent.input("Research the history of Python programming and save key points")
# Agent will search, then use write_memory() to save findings

# Later, recall research
agent.input("What did I learn about Python's history?")

File Format

Single File (Default)

Memories start in a single memory.md file using section headers:

## alice-notes

Alice prefers email communication
Works at TechCorp

## bob-notes

Bob from Marketing
Prefers phone calls

Auto-Split to Directory

When memory.md exceeds 3000 lines, it automatically migrates:

memory/

├── alice-notes.md

├── bob-notes.md

└── project-x.md

Best Practices

1. Use Descriptive Keys

keys.py

# Good
memory.write_memory("alice-techcorp-contact-info", content)

# Bad
memory.write_memory("note1", content)

2. Structure Your Content

Use markdown formatting for better organization:

structure.py

content = """# Alice - TechCorp

## Contact Info
- Email: alice@techcorp.com

## Projects
- Interested in API product
"""
memory.write_memory("alice-techcorp", content)

Tools

Agent Emails