hmc-memory 2.5.0

MemoryAI v2.0 — Living Brain for AI Agents. Emotion State Engine, Context Guard, DNA-protected memories, Multi-Agent Mesh, Hebbian learning, Ebbinghaus decay, Sleep consolidation, Personality synthesis, Causal reasoning.

MemoryAI — Python SDK

A brain for your AI agent. Store, recall, and manage context across sessions — memories persist and strengthen with use, just like the human mind.

Install

pip install hmc-memory

Quick Start

from memoryai import MemoryAI

mem = MemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev")

# Bootstrap — load context at session start
ctx = mem.bootstrap(task_description="Fix auth bug", project_name="my-app")
print(ctx["context_block"])

# Store — save what you learn
mem.store("User prefers dark mode", tags=["preferences"], priority="hot")

# Recall — search memory
for r in mem.recall("user preferences"):
    print(f"[{r.score:.0%}] {r.content}")

# Learn — store action + result + lesson
mem.learn(action="Fixed N+1 query", result="Response time 2s → 50ms", lesson="Always check ORM queries")

# Compact — consolidate session into key memories
mem.compact("Session transcript...", task_context="Refactoring auth")

mem.close()

Async

from memoryai import AsyncMemoryAI

async with AsyncMemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev") as mem:
    await mem.store("Important context", tags=["project"])
    results = await mem.recall("project context")

IDE Integration (MCP)

Works with Cursor, VS Code, Claude Desktop, Windsurf, Kiro, and OpenClaw via MCP server. See Integration Guide.

Agent Loop — turn memory into a working brain

The SDK ships MemoryAgent, a small ReAct-style executor that wires the memory primitives into a full operating loop:

bootstrap → [recall → pitfall_check → think → act → store/feedback]* → done

It is model-agnostic — you plug in any LLM and your own tools:

from memoryai import MemoryAI, MemoryAgent

mem = MemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev")

def my_llm(prompt: str, context: str) -> str:
    # Return a JSON decision string. Wire this to any model you like.
    # {"thought":..., "tool":..., "args":{...}, "done":false, "final":...}
    ...

tools = {
    "search_web": lambda q: "...",
    "run_tests":  lambda: "12 passed",
}

agent = MemoryAgent(mem, llm=my_llm, tools=tools)
result = agent.run("Fix the failing auth test")

print(result.final)
for step in result.steps:
    print(step.tool, step.observation)

What the loop does automatically:

• Bootstrap — loads DNA + recent activity so the agent starts informed.
• Recall — pulls memory relevant to the task before each decision.
• Pitfall check — queries known failures before acting, so the agent avoids repeating mistakes.
• Feedback — reports recall quality so the brain self-improves (helpful recalls get boosted, unhelpful ones fade).
• Outcome storage — successes become episodic memories; failures become DNA-protected pitfalls.
• State persistence — saves plan/cursor so a future session can resume.

The lower-level primitives are also available directly on the client: pitfall_check, procedure_check, feedback, predict, save_state, restore_state (sync and async).

How Your Agent's Brain Works

Memories are processed through 4 stages — just like the human brain:

	Stage	What it does	Like...
⚡	Instant Recall	What's on the tip of your tongue. Always ready, zero delay.	Remembering your own name
🔍	Deep Search	Scans long-term memory, finds matches by meaning — not just keywords.	"Where did I put that...?"
🧠	Reasoning	Reads multiple memories, connects the dots, synthesizes a precise answer. (Pro)	Thinking hard about it
📦	Archive	Compressed long-term storage. Memories age naturally, but nothing is truly forgotten.	That thing from 6 months ago

The more you recall a memory, the stronger it gets. Unused memories gently fade to deeper storage — but deeper recall can always bring them back.

Features

• 🔥 Hot / 🌤️ Warm / ❄️ Cold — Priority levels mirror how the brain stores memories
• Associative connections — Related memories link automatically, like neurons forming pathways
• Entity tracking — Recognizes files, people, packages, and URLs in your context
• Session recovery — Pick up exactly where you left off, every time
• Collective knowledge — Shared intelligence pool across users (anonymized, opt-in)
• Smart deduplication — Same knowledge stored once, no matter how many times you mention it
• Contradiction detection — Outdated info is flagged when newer facts arrive

Legacy Imports

Backward compatible — these still work:

from cortexmemory import MemoryAI      # OK
from hybridmemory import HybridMemory  # OK — alias for MemoryAI

Get an API Key

curl -X POST https://memoryai.dev/v1/admin/provision \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "tos_accepted": true}'

Or visit https://memoryai.dev to create one instantly.

Links

• PyPI: https://pypi.org/project/hmc-memory/
• Website: https://memoryai.dev
• Integration Guide: INTEGRATION-GUIDE.md