How to Integrate Memory Into Agents¶

Use this guide when you want to add memory to generated agent code without mixing it up with the top-level CLI memory backend.

Generate the Scaffold¶

The supported generator entrypoint is amplihack new, not the older goal-agent generate commands.

amplihack new \
  --file prompt.md \
  --name my-memory-agent \
  --enable-memory \
  --sdk copilot

This gives you a standalone package with:

• main.py
• memory_config.yaml
• memory/
• amplihack-memory-lib in requirements.txt
• helper functions injected into main.py

Install the Package Dependencies¶

cd goal_agents/my-memory-agent
python -m pip install -r requirements.txt

Use the Generated Memory Helpers¶

The generated package exposes helper functions such as:

• store_success(context, outcome, confidence=...)
• store_failure(context, outcome, confidence=...)
• store_pattern(context, outcome, confidence=...)
• store_insight(context, outcome, confidence=...)
• recall_relevant(query, limit=...)
• cleanup_memory()

A minimal integration pattern is to recall relevant experience before the run and store the result afterward.

recent = recall_relevant(initial_prompt, limit=3)
for item in recent:
    print("Previous experience: {} -> {}".format(item.context, item.outcome))

exit_code = auto_mode.run()

if exit_code == 0:
    store_success(
        context="Goal execution completed",
        outcome=initial_prompt,
        confidence=0.95,
    )
else:
    store_failure(
        context="Goal execution failed",
        outcome="Exit code {}".format(exit_code),
        confidence=0.95,
    )

Keep the Two Memory Surfaces Straight¶

The generated package and the top-level CLI graph are different systems.

If you want to inspect the top-level CLI graph, use:

amplihack memory tree --depth 2

If you want to move an agent-local hierarchical memory store between environments, use:

amplihack memory export --agent incident-memory-agent --output ./incident-memory.json
amplihack memory import --agent incident-memory-agent --input ./incident-memory.json --merge

Do not expect those commands to be a direct live view into a generated agent's local ./memory/ directory.

Configure Kuzu-backed Graph Paths¶

For lower-level Kuzu graph integrations and agent-local hierarchical stores, the preferred environment variable is:

export AMPLIHACK_GRAPH_DB_PATH=/path/to/memory_kuzu.db

AMPLIHACK_KUZU_DB_PATH still exists as a deprecated alias.

The top-level amplihack memory tree command does not read this setting; it opens the SQLite MemoryDatabase unless you change code.

Related Docs¶

• Agent Memory Quickstart
• Memory tutorial
• Memory-enabled agents architecture
• Memory CLI reference