MemAgent-JSON

A minimal AI assistant with persistent JSON-based memory management. This project implements an intelligent agent that can learn facts, procedures, and maintain conversation history using a structured memory system.

🚀 Features

Memory Management

• Facts Memory: Store and retrieve semantic knowledge and facts
• Procedures Memory: Learn and execute step-by-step procedures
• Interactions Memory: Maintain conversation history and context
• Short-term Memory: Fast access to recent, contextually relevant information

Learning Capabilities

• Fact Learning: Learn new facts using natural language commands
• Procedure Learning: Learn multi-step procedures with detailed instructions
• Context-Aware Responses: Use memory to provide personalized, context-aware answers

Search & Retrieval

• Keyword-based Search: Intelligent search across all memory types
• Relevance Scoring: Results ranked by relevance to queries
• Context Building: Automatic context generation for LLM interactions

🏗️ Architecture

memagent-json/
├── agent.py              # Main agent logic and OpenAI integration
├── memory.py             # Core memory management system
├── main.py               # Console chat interface
├── simple_chat.py        # Streamlit web chat interface
├── config/               # Configuration and command definitions
│   └── commands.py      # Single source of truth for command formats
├── json_memory/          # Persistent JSON storage
│   ├── facts.json       # Stored facts and knowledge
│   ├── procedures.json  # Stored procedures and steps
│   ├── interactions.json # Conversation history
│   └── short_term_memory.json # Recent context
├── prompts/              # System prompts and templates
│   └── facts.py         # Initial facts and system prompt
├── utils/                # Core utilities
│   ├── search.py        # Search functionality
│   ├── json_file_utils.py # File operations
│   └── json_parser.py   # JSON parsing utilities
└── tests/                # Comprehensive test suite
    ├── test_agent.py    # Agent functionality tests
    └── test_memory.py   # Memory system tests

🧠 Memory System Flow

graph TD
    A[User Input] --> B{Input Type Detection}

    B -->|Fact Command| C[Facts Memory]
    B -->|Procedure Command| D[Procedures Memory]
    B -->|Regular Chat| E[Interactions Memory]
    B -->|Context Info| F[Short-term Memory]

    C --> G[Store Fact]
    D --> H[Store Procedure]
    E --> I[Store Interaction]
    F --> J[Store Context]

    G --> K[Update facts.json]
    H --> L[Update procedures.json]
    I --> M[Update interactions.json]
    J --> N[Update short_term_memory.json]

    K --> O[Memory Retrieval]
    L --> O
    M --> O
    N --> O

    O --> P[Search & Context Building]
    P --> Q[LLM Processing]
    Q --> R[Generate Response]
    R --> S[Update Short-term Memory]
    S --> T[Return Response to User]

    subgraph "Memory Types"
        C
        D
        E
        F
    end

    subgraph "Storage"
        K
        L
        M
        N
    end

    subgraph "Processing"
        O
        P
        Q
        R
    end

    style A fill:#e1f5fe
    style T fill:#e8f5e8
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#e0f2f1
    style F fill:#fff8e1

Loading

Process Message Flow

graph TD
    A[User Input] --> B[Agent.process_message]
    B --> C[extract_and_learn]

    C --> D{Check for Learning Commands}
    D -->|Fact Command Found| E[learn_fact]
    D -->|Procedure Command Found| F[learn_procedure]
    D -->|No Learning Command| G[build_messages]

    E --> H[memory.add_fact]
    F --> I[memory.add_procedure]

    H --> J[Save to facts.json]
    I --> K[Save to procedures.json]

    G --> L[memory.get_context]
    L --> M[Search Recent Interactions]
    L --> N[Search Relevant Facts]
    L --> O[Search Relevant Procedures]
    L --> P[Get Short-term Memory]

    M --> Q[Build Context String]
    N --> Q
    O --> Q
    P --> Q

    Q --> R[Create OpenAI Messages]
    R --> S[Call OpenAI API]
    S --> T[Get Response]
    T --> U[memory.add_interaction]
    U --> V[Save to interactions.json]
    V --> W[Return Response to User]

    subgraph "Learning Flow"
        E
        F
        H
        I
    end

    subgraph "Context Building"
        L
        M
        N
        O
        P
        Q
    end

    subgraph "Response Generation"
        R
        S
        T
        U
    end

    style A fill:#e1f5fe
    style W fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#f3e5f5
    style U fill:#e0f2f1

Loading

🛠️ Installation

1. Clone the repository

   git clone <repository-url>
   cd memagent-json

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment variables

   cp env.example .env

   Edit .env and add your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   

🚀 Quick Start

Run the Web Application (Streamlit)

streamlit run simple_chat.py

Run the Console Application

python main.py

🚀 Getting Started

Option 1: Web Interface (Streamlit)

Start the interactive web chat interface:

streamlit run simple_chat.py

This will open a web browser with a clean chat interface where you can:

• Chat naturally with your AI agent
• View memory statistics in real-time (facts, procedures, interactions)
• See learning examples right in the interface
• Watch the agent learn as you teach it new things
• No commands to remember - just type naturally!

Features:

• 🧠 Real-time memory visualization
• 💬 Chat bubble interface
• 📊 Memory statistics dashboard
• 🎯 Learning command examples
• 🔄 Persistent memory across sessions

Option 2: Console Interface

For a simple command-line chat experience:

python main.py

This provides a clean console interface where you can:

• Chat directly in your terminal
• Teach facts and procedures through natural conversation
• Exit easily by typing 'exit', 'quit', or 'bye'
• No complex commands - just start chatting!

Example console session:

🧠 MemAgent Simple Chat
========================================
Chat with an AI that remembers everything!
Type 'exit' to quit.
----------------------------------------
🚀 Initializing agent...
✅ Agent ready! Start chatting below.

👤 You: Remember that my favorite color is blue
🤔 Thinking...
🤖 Assistant: I'll remember that your favorite color is blue!

👤 You: What's my favorite color?
🤔 Thinking...
🤖 Assistant: Your favorite color is blue!

👤 You: exit
👋 Goodbye! Your agent will remember everything you taught it.

📖 Usage

Learning Facts

Teach the agent new facts using these formats:

Remember that Python is a programming language
Remember this fact: The user's name is John
Remember this knowledge: Machine learning uses algorithms

Learning Procedures

Teach the agent procedures with steps:

Remember the procedure making coffee: boil water, add coffee grounds, stir, wait 5 minutes
Remember the steps for greeting: say hello, ask how they are, wait for response

Direct Memory Operations

from memory import Memory

# Initialize memory
memory = Memory()

# Add facts
memory.add_fact("The sky is blue", "semantic")

# Add procedures
memory.add_procedure("Cooking", ["1. Get ingredients", "2. Cook", "3. Serve"], "Cooking a meal")

# Add interactions
memory.add_interaction("Hello", "Hi there!", {"context": "greeting"})

# Add to short-term memory
memory.add_to_short_term_memory("Going to the store")

# Search memory
facts = memory.search_facts("sky")
procedures = memory.search_procedures("cooking")
interactions = memory.search_interactions("hello")

Example from main.py

from memory import Memory

memory = Memory()

memory.add_fact("The sky is blue", "semantic")
memory.add_procedure("Cooking", ["1. Get ingredients", "2. Cook", "3. Serve"], "Cooking a meal")
memory.add_interaction("Hello, how are you?", "I'm good, thank you!", {"weather": "sunny"})
memory.add_to_short_term_memory("I'm going to the store")

print(memory.facts)
print(memory.procedures)
print(memory.interactions)

🧪 Testing

Run the comprehensive test suite:

python -m pytest tests/ -v

Test Coverage

The test suite covers:

• Memory Operations: Get, search and save operations for all memory types
• Search Functionality: Keyword-based search across memory
• Agent Learning: Fact and procedure learning capabilities
• Message Processing: End-to-end message handling
• Error Handling: Graceful error management
• Data Consistency: Format validation and structure integrity

🔧 Configuration

Command Formats

All command formats are centralized in config/commands.py:

• Fact Commands: ["remember that", "remember this", "remember this fact", ...]
• Procedure Commands: ["remember the steps for", "remember the procedure", "remember the steps"]

Memory Settings

• Short-term Memory Size: Configurable limit (default: 10 items)
• Search Limits: Configurable result limits (default: 3 items)
• Storage Location: Configurable JSON storage directory

🏛️ Design Principles

Single Source of Truth

• Command formats defined once in config/commands.py
• Consistent format validation across the system
• Centralized configuration management

Memory Hierarchy

1. Short-term Memory: Fast access, recent context
2. Facts Memory: Semantic knowledge and facts
3. Procedures Memory: Step-by-step instructions
4. Interactions Memory: Conversation history

Error Handling

• Graceful degradation on API failures
• Comprehensive input validation
• Detailed error messages for debugging

🔍 Search Algorithm

The search system uses keyword-based matching with relevance scoring:

1. Query Processing: Split into individual terms
2. Case-insensitive Matching: Find terms in content
3. Scoring: Count matching terms per item
4. Ranking: Sort by relevance score
5. Limiting: Return top N results

📊 Memory Structure

Facts

{
  "fact": "The sky is blue",
  "type": "semantic",
  "timestamp": "2025-06-18T17:53:05.784571"
}

Procedures

{
  "name": "Cooking",
  "description": "Cooking a meal",
  "steps": ["1. Get ingredients", "2. Cook", "3. Serve"],
  "timestamp": "2025-06-18T17:59:13.273291"
}

Interactions

{
  "user_message": "Hello, how are you?",
  "agent_message": "I'm good, thank you!",
  "metadata": { "weather": "sunny" },
  "timestamp": "2025-06-18T17:53:05.784828"
}

Short-term Memory

{
  "content": "I'm going to the store",
  "importance": 1.0,
  "timestamp": "2025-06-18T17:59:13.273571"
}

Development Guidelines

• Testing: Write comprehensive tests for all new features
• Documentation: Update README and docstrings
• Code Style: Follow Python PEP 8 guidelines
• Error Handling: Implement graceful error handling
• Consistency: Maintain single source of truth principles