Agentic Memory (A-MEM)

Use the following methods to manage individual memory entries in the system:

• add_note(content, tags=None, category=None, timestamp=None): Creates a new memory. If metadata like tags, category, or timestamp (format YYYYMMDDHHmm) is provided, it is stored with the note. The system automatically generates context and keywords.
• update(memory_id, content): Updates the content of an existing memory identified by memory_id.
• delete(memory_id): Removes a memory from the system.

# Simple addition
memory_id = memory_system.add_note("Deep learning neural networks")

# Addition with metadata
memory_id = memory_system.add_note(
    content="Machine learning project notes",
    tags=["ml", "project"],
    category="Research",
    timestamp="202503021500"
)

# Update
memory_system.update(memory_id, content="Updated content about deep learning")

# Delete
memory_system.delete(memory_id)

The system provides several ways to retrieve information based on a query string:

• search(query, k=5): Performs hybrid retrieval returning a list of dictionaries containing id, content, context, keywords, and a similarity score.
• search_agentic(query, k=5): A specialized search that retrieves relevant memories via ChromaDB and then includes their linked "neighbor" memories (those explicitly connected via links) to provide a richer context. Returns a list of dictionaries with an is_neighbor boolean flag.
• find_related_memories(query, k=5): Returns a formatted string of related memories and their indices, useful for feeding into an LLM prompt.

# Standard hybrid search
results = memory_system.search("foxes and dogs", k=3)
for res in results:
    print(f"ID: {res['id']}, Content: {res['content']}")

# Agentic search (includes neighbors)
agentic_results = memory_system.search_agentic("foxes and dogs", k=5)

The CopiedChromaRetriever creates an isolated, temporary copy of an existing ChromaDB collection. This is ideal for giving an agent a 'snapshot' of a shared memory base that it can modify without affecting the original source.

How it works

1. It connects to a source directory and collection.
2. It creates a new temporary directory using tempfile.TemporaryDirectory.
3. It clones all documents, metadatas, and embeddings from the source to the temporary destination.
4. It automatically cleans up the temporary directory and deletes the cloned collection when the object is closed or goes out of scope (via __exit__).

Initialization Parameters

• directory (Optional[str]): Path to the source ChromaDB storage.
• collection_name (str): Name of the source collection to copy.
• _dest_collection_name (Optional[str]): Optional name for the new collection. Defaults to {collection_name}__clone.
• _copy_batch_size (int): Number of documents to copy per batch (default 10).

from agentic_memory.retrievers import CopiedChromaRetriever

# Create an isolated sandbox from the main memory
with CopiedChromaRetriever(directory="~/.chromadb", collection_name="shared_mem") as sandbox:
    # Sandbox can add/delete documents without affecting the source
    sandbox.add_document("Sandbox note", {}, "temp_id")
    results = sandbox.search("shared info")
    print(results)

# Once the 'with' block exits, the sandbox is automatically destroyed.

The get_completion method in LLMController supports structured output via the response_format parameter. This is particularly useful for metadata generation where you need the LLM to return a valid JSON object following a specific schema.

• prompt (str): The input text.
• response_format (dict, optional): A dictionary defining the JSON schema. For OpenAI, this typically follows the OpenAI JSON schema format.
• temperature (float, optional): Controls randomness. Defaults to 0.7.

# Example of requesting a specific JSON structure
response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "memory_metadata",
        "schema": {
            "type": "object",
            "properties": {
                "topic": {"type": "string"},
                "importance": {"type": "number"}
            },
            "required": ["topic", "importance"]
        }
    }
}

response = controller.get_completion(
    prompt="Extract metadata from: The meeting about project X was very important.",
    response_format=response_format
)