mnemonic-sdk 0.1.1

Persistent cognitive infrastructure for AI agents — memory, procedural learning, and cross-agent intelligence that compounds over time.

🧠 Mnemonic SDKs

Persistent cognitive infrastructure for AI agents.

Agents that remember. Agents that improve. Agents that never make the same mistake twice.

---

The Problem

Every AI agent built today has the same fatal flaw: it forgets everything.

Run it a thousand times — it still makes the same mistakes on run 1000 as it did on run 1. That's not intelligence. That's an expensive loop.

# Without Mnemonic — agent starts from zero every time
response = agent.run("fix authentication bug")  # 5 retries, 4 mins, 1 failure
response = agent.run("fix authentication bug")  # 5 retries, 4 mins, 1 failure  
response = agent.run("fix authentication bug")  # 5 retries, 4 mins, 1 failure

# With Mnemonic — agent learns from every execution
ctx = mnemonic.recall(agent_id="coder", task="fix authentication bug")
response = agent.run("fix authentication bug", context=ctx)
mnemonic.capture(agent_id="coder", task="fix auth bug", success=True)

# Run 1:  5 retries · 4 minutes  · 1 failure
# Run 5:  3 retries · 2 minutes  · 0 failures
# Run 10: 1 retry   · 45 seconds · 0 failures  ← Mnemonic is working

70% reduction in token expenditure. Measurable. Reproducible. Compounding.

---

What Is Mnemonic?

Mnemonic is a cognitive infrastructure layer that sits between your AI agents and the world. Two SDK calls bracket every agent execution:

recall()  → before the agent runs  → inject accumulated intelligence
capture() → after the agent runs   → extract and store new lessons

Every execution gets reflected on by an LLM. Lessons are embedded into a vector knowledge graph. Relevant knowledge is recalled with semantic precision before the next run.

The agent doesn't just run. It evolves.

---

The Four Pillars of Agent Cognition

Pillar	What it does
Procedural Learning	Agents learn HOW to do tasks better from outcomes
Episodic Memory	Every execution is logged, reflected on, and distilled
Cross-Agent Intelligence	Agent A learns → Agent B starts smarter (network effect)
Workflow Evolution	Procedures self-optimise based on success and failure patterns

---

Install

Python

pip install mnemonic-sdk

With integrations:

pip install mnemonic-sdk[openai]      # OpenAI SDK wrapper
pip install mnemonic-sdk[anthropic]   # Anthropic SDK wrapper  
pip install mnemonic-sdk[all]         # Everything

JavaScript / TypeScript

npm install @mnemonicai.official/sdk-js

---

Quick Start

Python

from mnemonic import Mnemonic

m = Mnemonic(api_key="mnemonic_sk_...")

# Step 1: Recall accumulated intelligence before the task
context = m.recall(
    agent_id="coder-agent",
    task="fix JWT authentication bug",
    as_prompt=True  # returns formatted string for LLM injection
)

# Step 2: Run your agent with the recalled context
response = your_agent.run(task, context=context)

# Step 3: Capture the outcome — reflection happens automatically
m.capture(
    agent_id="coder-agent",
    task="fix JWT authentication bug",
    actions=[{"type": "edit", "target": "auth.py"}],
    output=response.output,
    success=True,
    retries=2,
    time_taken=45000  # ms
)

JavaScript / TypeScript

import { Mnemonic } from '@mnemonicai.official/sdk-js';

const mnemonic = new Mnemonic({ apiKey: 'mnemonic_sk_...' });

// Recall before task
const memory = await mnemonic.recall({
  agentId: 'coder-agent',
  task: 'fix JWT authentication bug',
  asPrompt: true
});

// Run agent with context
const result = await yourAgent.run(task, { context: memory.prompt });

// Capture after task
await mnemonic.capture({
  agentId: 'coder-agent',
  task: 'fix JWT authentication bug',
  actions: [{ type: 'edit', target: 'auth.py' }],
  output: result.output,
  success: true,
  retries: 2,
  timeTaken: 45000
});

---

OpenAI Integration

from mnemonic.integrations.openai import MnemonicOpenAI
from openai import OpenAI

client = MnemonicOpenAI(
    openai_client=OpenAI(),
    mnemonic_api_key="mnemonic_sk_...",
    agent_id="my-openai-agent"
)

# Mnemonic wraps every chat completion automatically
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Fix the authentication bug"}]
)
# recall() and capture() happen automatically — zero code changes

---

Claude / Anthropic Integration

from mnemonic.integrations.claude import MnemonicClaude
from anthropic import Anthropic

client = MnemonicClaude(
    anthropic_client=Anthropic(),
    mnemonic_api_key="mnemonic_sk_...",
    agent_id="my-claude-agent"
)

response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Deploy to production"}]
)
# Fully wrapped — memory handled transparently

---

The Network Effect

The real breakthrough isn't what one agent learns. It's what happens when thousands of agents learn simultaneously and share that intelligence.

Agent A encounters a production failure
  → Mnemonic reflects, extracts the operational lesson
  → Lesson propagates across the cognitive layer

Agent B — running the same task class at a different company
  → Starts with Agent A's accumulated intelligence
  → Never makes that mistake

That's collective intelligence. That's the network effect nobody in this space has architected for.

---

Benchmark Results

Run against a real coding agent on a repeating task class (authentication bug fixes):

Run	Retries	Time	Failures	Token Cost
1	5	4min	1	100%
3	3	2min	0	68%
5	2	90s	0	45%
10	1	45s	0	30%

70% token reduction. 94% time reduction. Zero repeated failures.

---

API Reference

recall(agent_id, task, limit=10, as_prompt=False)

Semantic vector search across accumulated lessons and procedures. Returns the most relevant operational intelligence for the given task.

Returns: RecallResponse with lessons, procedures, and optionally prompt (formatted for LLM injection).

capture(agent_id, task, actions, output, success, retries=0, time_taken=None)

Logs an agent execution. Triggers async reflection via LLM — extracts lessons, embeds them, stores in vector graph. Returns immediately (reflection is non-blocking).

get_agent_stats(agent_id)

Returns improvement metrics: retry reduction, token savings, success rate trends across all executions.

feedback(lesson_id, rating)

Rate a lesson: useful · outdated · wrong · great. Adjusts confidence scores in real time.

---

Architecture

Your Agent
    │
    ├── recall()  ←─── pgvector HNSW semantic search
    │                  ↑
    │              Lesson Store
    │                  ↑
    └── capture() ───→ ARQ Worker → Claude Sonnet 4.5
                                    (reflection engine)
                                    ↓
                                Extract lessons
                                Embed (1536-dim)
                                Store + reinforce

Stack: FastAPI · PostgreSQL 16 · pgvector · Redis · ARQ · Claude Sonnet 4.5 · OpenAI text-embedding-3-small

---

Self-Hosting

git clone https://github.com/Nirvana3339/mnemonic
cd mnemonic

cp .env.example .env
# Fill in: DATABASE_URL, REDIS_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY, SECRET_KEY

docker-compose up

API available at http://localhost:8001/api/health

---

Pricing

Plan	Price	Agents	Reflections
OSS / Self-Host	Free forever	Unlimited	Unlimited
Starter	$29/month	5	1,000/month
Pro	$79/month	25	5,000/month
Team	$199/month	Unlimited	10,000/month
Enterprise	Custom	Unlimited	Unlimited

---

Repository Structure

mnemonic-sdks/
├── python/                     ← pip install mnemonic-sdk
│   ├── mnemonic/
│   │   ├── client.py           # Synchronous client
│   │   ├── async_client.py     # Async client
│   │   ├── models.py           # Pydantic models
│   │   ├── exceptions.py       # Error types
│   │   └── integrations/
│   │       ├── openai.py       # OpenAI SDK wrapper
│   │       └── claude.py       # Anthropic SDK wrapper
│   ├── examples/
│   └── pyproject.toml
│
├── javascript/                 ← npm install @mnemonicai.official/sdk-js
│   ├── src/
│   │   ├── client.ts           # Main client
│   │   ├── types.ts            # TypeScript interfaces
│   │   ├── errors.ts           # Error classes
│   │   └── index.ts            # Exports
│   ├── examples/
│   └── package.json
│
└── examples/                   ← Cross-language examples

---

Roadmap

• v1 (Now): Procedural learning · Python + JS SDKs · REST API · Self-hostable
• v2: Cross-agent knowledge graph · LangChain + AutoGen integrations · JS async client
• v3: Org cognition · Slack/Notion/Jira connectors · SOC 2
• v4: Workflow evolution · Causal reasoning · Domain expansion (sales, legal, finance)

---

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines.

git clone https://github.com/Nirvana3339/mnemonic-sdks
cd mnemonic-sdks/python
pip install -e ".[all]"

---

License

MIT — see LICENSE

---

Built by Nishant Vanawala in Melbourne, Australia

The cognitive operating layer for the age of autonomous agents.

mnemonic.dev · [e-mail] · npm