memory.md

Memory Module Guide

This document explains DevAll's memory system: memory list config, built-in store implementations, how agent nodes attach memories, and troubleshooting tips. Core code lives in entity/configs/memory.py and node/agent/memory/*.py.

1. Architecture

1. Memory Store – Declared under memory[] in YAML with name, type, and config. Types are registered via register_memory_store() and point to concrete implementations.
2. Memory Attachment – Referenced inside agent nodes via AgentConfig.memories. Each MemoryAttachmentConfig defines read/write strategy and retrieval stages.
3. MemoryManager – Builds store instances at runtime based on attachments and orchestrates load(), retrieve(), update(), save().
4. Embedding – SimpleMemoryConfig and FileMemoryConfig embed EmbeddingConfig, and EmbeddingFactory instantiates OpenAI or local vector models.

2. Memory Sample Config

memory:
  - name: convo_cache
    type: simple
    config:
      memory_path: WareHouse/shared/simple.json
      embedding:
        provider: openai
        model: text-embedding-3-small
        api_key: ${API_KEY}
  - name: project_docs
    type: file
    config:
      index_path: WareHouse/index/project_docs.json
      file_sources:
        - path: docs/
          file_types: [".md", ".mdx"]
          recursive: true
      embedding:
        provider: openai
        model: text-embedding-3-small

Mem0 Memory Config

memory:
  - name: agent_memory
    type: mem0
    config:
      api_key: ${MEM0_API_KEY}
      agent_id: my-agent

Valkey Memory Config

memory:
  - name: chatdev_memory
    type: valkey
    config:
      host: localhost
      port: 6379
      index_name: chatdev_memory
      ttl_seconds: 86400
      embedding:
        provider: openai
        model: text-embedding-3-small
        api_key: ${API_KEY}

3. Built-in Store Comparison

Type	Path	Highlights	Best for
simple	node/agent/memory/simple_memory.py	Optional disk persistence (JSON) after runs; FAISS + semantic rerank; read/write capable.	Small conversation history, prototypes.
file	node/agent/memory/file_memory.py	Chunks files/dirs into a vector index, read-only, auto rebuilds when files change.	Knowledge bases, doc QA.
blackboard	node/agent/memory/blackboard_memory.py	Lightweight append-only log trimmed by time/count; no vector search.	Broadcast boards, pipeline debugging.
mem0	node/agent/memory/mem0_memory.py	Cloud-managed by Mem0; semantic search + graph relationships; no local embeddings or persistence needed. Requires mem0ai package.	Production memory, cross-session persistence, multi-agent memory sharing.
valkey	node/agent/memory/valkey_memory.py	HNSW vector index via Valkey Search; server-side persistence, cross-process sharing, TTL auto-expiry. Requires valkey-glide-sync package.	Self-hosted persistent memory, multi-process deployments, privacy-sensitive environments.

All stores register through register_memory_store() so summaries show up in UI via MemoryStoreConfig.field_specs().

4. MemoryAttachmentConfig Fields

Field	Description
name	Target Memory Store name (must be unique inside stores[]).
retrieve_stage	Optional list limiting retrieval to certain AgentExecFlowStage values (pre, plan, gen, critique, etc.). Empty means all stages.
top_k	Number of items per retrieval (default 3).
similarity_threshold	Minimum similarity cutoff (-1 disables filtering).
read / write	Whether this node can read from / write back to the store.

Agent node example:

nodes:
  - id: answer
    type: agent
    config:
      provider: openai
      model: gpt-4o-mini
      prompt_template: answer_user
      memories:
        - name: convo_cache
          retrieve_stage: ["gen"]
          top_k: 5
          read: true
          write: true
        - name: project_docs
          read: true
          write: false

Execution order:

1. When the node enters gen, MemoryManager iterates attachments.
2. Attachments matching the stage and read=true call retrieve() on their store.
3. Retrieved items are formatted under a "===== Related Memories =====" block in the agent context.
4. After completion, attachments with write=true call update() and optionally save().

5. Store Details

All memory stores persist a unified MemoryItem structure containing:

• content_summary – trimmed text used for embedding search.
• input_snapshot / output_snapshot – serialized message blocks (with base64 attachments) preserving multimodal context.
• metadata – store-specific telemetry (role, previews, attachment IDs, etc.). This schema lets multimodal outputs flow into Memory/Thinking modules without extra plumbing.

5.1 SimpleMemory

• Path – SimpleMemoryConfig.memory_path (or auto). Defaults to in-memory.
• Retrieval – Build a query from the prompt, trim it, embed, query FAISS IndexFlatIP, then apply semantic rerank (Jaccard/LCS).
• Write – update() builds a MemoryContentSnapshot (text + blocks) for both input/output, deduplicates via hashed summary, embeds the summary, and stores the snapshots/attachments metadata.
• Tips – Tune max_content_length, top_k, and similarity_threshold to avoid irrelevant context.

5.2 FileMemory

• Config – Requires at least one file_sources entry (paths, suffix filters, recursion, encoding). index_path is mandatory for incremental updates.
• Indexing – Scan files → chunk (default 500 chars, 50 overlap) → embed → persist JSON with file_metadata.
• Retrieval – Uses FAISS cosine similarity. Read-only; update() unsupported.
• Maintenance – load() checks file hashes and rebuilds if needed. Store index_path on persistent storage.

5.3 BlackboardMemory

• Config – memory_path (or auto) plus max_items. Creates the file in the session directory if missing.
• Retrieval – Returns the latest top_k entries ordered by time.
• Write – update() appends the latest snapshot (input/output blocks, attachments, previews). No embeddings are generated, so retrieval is purely recency-based.

5.4 Mem0Memory

• Config – Requires api_key (from app.mem0.ai). Optional user_id, agent_id, org_id, project_id for scoping.
• Entity scoping: user_id and agent_id are independent dimensions — both can be included simultaneously in add() and search() calls. When both are configured, retrieval uses an OR filter ({"OR": [{"user_id": ...}, {"agent_id": ...}]}) to search across both scopes. Writes include both IDs when available.
• Retrieval – Uses Mem0's server-side semantic search. Supports top_k and similarity_threshold via MemoryAttachmentConfig.
• Write – update() sends only user input to Mem0 via the SDK (as role: "user" messages). Assistant output is excluded to prevent noise memories from the LLM's responses being extracted as facts.
• Persistence – Fully cloud-managed. load() and save() are no-ops. Memories persist across runs and sessions automatically.
• Dependencies – Requires mem0ai package (pip install mem0ai).

5.5 ValkeyMemory

• Config – Specify connection parameters and index settings via ValkeyMemoryConfig.

  memory:
    - name: chatdev_memory
      type: valkey
      config:
        host: localhost
        port: 6379
        index_name: chatdev_memory
        ttl_seconds: 86400
        embedding:
          provider: openai
          model: text-embedding-3-small
          api_key: ${API_KEY}

  Field	Description	Default
  host	Valkey server address	localhost
  port	Port (1-65535)	6379
  username	ACL username	None
  password	Auth password	None
  db	Database index (0-15)	0
  use_tls	Enable TLS encryption for the connection	false
  index_name	FT index name	memory_index
  key_prefix	Hash key prefix	memory:
  ttl_seconds	Memory expiry in seconds; None means never expire	None
  embedding	Nested EmbeddingConfig (required)	—

• Index creation – On first instantiation, automatically calls FT.CREATE to build an HNSW vector index (COSINE distance) with content_summary (TEXT), agent_role (TAG), timestamp (NUMERIC), and embedding (VECTOR) fields. Silently skips if the index already exists.
• Retrieval – Executes a KNN query via FT.SEARCH, returns top-k results sorted by cosine similarity. Low-relevance results are filtered by similarity_threshold.
• Write – update() encodes input text into a float32 vector and stores it as a Valkey Hash (HSET). When ttl_seconds is configured, EXPIRE is called to set the TTL.
• Persistence – Managed by the Valkey server. load() and save() are no-ops. Data survives process restarts, and multiple processes can concurrently read/write the same index.
• Error handling – If Valkey does not have the Search module loaded, initialization raises a RuntimeError with installation guidance.
• Dependencies – Requires valkey-glide-sync package (pip install 'chatdev[valkey]').
• Best for – Self-hosted deployments needing persistence, cross-process sharing, and automatic expiry; a drop-in alternative to Mem0 when cloud services are not acceptable for privacy reasons.

6. EmbeddingConfig Notes

• Fields: provider, model, api_key, base_url, params.
• provider=openai uses the official client; override base_url for compatibility layers.
• params can include use_chunking, chunk_strategy, max_length, etc.
• provider=local expects params.model_path and depends on sentence-transformers.

7. Troubleshooting & Best Practices

• Duplicate names – The memory list enforces unique memory[] names. Duplicates raise ConfigError.
• Missing embeddings – SimpleMemory without embeddings downgrades to append-only; FileMemory errors out. Provide an embedding config whenever semantic search is required.
• Permissions – Ensure directories for memory_path/index_path are writable. Mount volumes when running inside containers.
• Performance – Pre-build large FileMemory indexes offline, use retrieve_stage to limit retrieval frequency, and tune top_k/similarity_threshold to balance recall vs. token cost.

8. Extending Memory

1. Implement a Config + Store (subclass MemoryBase).
2. Register via register_memory_store("my_store", config_cls=..., factory=..., summary="...") in node/agent/memory/registry.py.
3. Add FIELD_SPECS, then run python -m tools.export_design_template ... so the frontend picks up the enum.
4. Update this guide or ship a README detailing configuration knobs and boundaries.