Add Python SDK

[Atharva-Kanherkar]

Summary

• Adds agentic_memory.py — a single-file SDK exposing a Memory class that wraps the runtime with a clean, minimal API
• pip install agentic-memory then from agentic_memory import Memory just works
• Covers all core operations: remember(), remember_episode(), remember_procedure(), recall(), recall_episodes(), recall_procedures(), find_contradictions(), resolve_contradiction(), record_outcome(), forget(), get(), overview(), events()
• Re-exports key types (RankedResult, ProceduralMatch, ContradictionCandidate, ForgettingReport, model classes)
• m.runtime escape hatch for power users who need direct access
• 30 tests in tests/test_sdk.py, all passing

Usage

from agentic_memory import Memory

m = Memory()
m.remember("user prefers dark mode")
m.remember_episode("debugged auth flow for 2 hours", session="abc")
results = m.recall("what does the user prefer?")

Test plan

• 30 new SDK tests all pass
• 208 existing non-API tests still pass (no regressions)
• Verify pip install . and from agentic_memory import Memory works in a clean venv

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentic-memory	Ready	Preview, Comment	Mar 31, 2026 9:14pm

[Atharva-Kanherkar]

@claude review the PR/.

[claude]

Claude finished @Atharva-Kanherkar's task in 1m 46s —— View job

---

PR Review: Add Python SDK

Tasks:

• Gather context and read PR files
• Review agentic_memory.py (SDK implementation)
• Review tests/test_sdk.py
• Review pyproject.toml changes
• Post comprehensive review feedback

---

Summary

This is a clean, well-structured SDK addition. The Memory class provides a nice high-level interface with good documentation. A few issues worth addressing before merge:

---

Issues

Bug / API Design

1. type parameter shadows Python builtin — agentic_memory.py:345

def get(self, record_id: str, *, type: str) -> MemoryRecord | None:

Using type as a parameter name shadows the Python builtin type(). Should be renamed to memory_type (consistent with the types parameter in recall()) or kind. Fix this →

---

Performance

2. overview() loads all records into memory — agentic_memory.py:363-373

semantic_count = len(self._runtime.semantic_store.get_all_records())

get_all_records() loads all records to count them (O(N) memory). For large stores this is wasteful. This is a known limitation since the stores don't currently expose a count() method, but it's worth a comment in the docstring: "Note: loads all records into memory to count — may be slow for large stores."

---

Tests

3. test_find_contradictions doesn't verify meaningful behavior — tests/test_sdk.py:155-161

def test_find_contradictions(self, mem: Memory):
    id1 = mem.remember("the capital of France is Paris")
    id2 = mem.remember("the capital of France is Paris and it is lovely")
    candidates = mem.find_contradictions(id1)
    assert isinstance(candidates, list)  # ← just checks it's a list

This test doesn't assert that candidates contains the second (similar) memory, nor that the returned items are ContradictionCandidate instances. Should at minimum check all(isinstance(c, ContradictionCandidate) for c in candidates).

4. test_all_exports only checks two of the ten exports — tests/test_sdk.py:241-254

assert Memory is not None
assert RankedResult is not None
# MemoryRuntime, ContradictionCandidate, ProceduralMatch, ForgettingReport,
# SemanticMemory, EpisodicMemory, ProceduralMemory, MemoryRecord — not checked

Add assertions for all exported names. Fix this →

5. recall_by_vector has no test coverage — agentic_memory.py:240-258

The recall_by_vector() method is exposed on the Memory class but has no corresponding test in test_sdk.py. Add a basic test that stores a record, generates a vector via the embedder, and queries by that vector.

---

Minor / Nits

6. Repeated modality logic — agentic_memory.py:129, 167, 200

modality="text" if not media_ref else (media_type or "text"),

This same expression appears in all three remember* methods. Not a blocker, but extracting a helper _infer_modality(media_ref, media_type) would reduce duplication.

7. Missing __version__ — agentic_memory.py

For a pip-installable package, it's conventional to expose __version__ = "0.1.0" (or dynamically read from importlib.metadata). Low priority but standard practice.

8. remember_episode default participants — agentic_memory.py:158

participants=participants or ["user", "agent"],

Defaulting to ["user", "agent"] is opinionated for a general-purpose SDK. If a caller passes participants=[] they'll silently get the default. Consider participants or [] and let the underlying model handle the default, or at least document this default in the docstring.

---

Positives

• API surface is minimal and intuitive — remember / recall / forget maps naturally to the cognitive model
• dry_run on forget() is a nice safety affordance
• escape_hatch via m.runtime is well thought-out for power users
• Docstrings are thorough and use NumPy-style sections
• pyproject.toml change is minimal and correct (just adds agentic_memory to py-modules)
• 30 tests provide good baseline coverage

---

Overall this is merge-ready with the type builtin shadowing fixed. The test gaps (items 3–5) are worth addressing but not blockers.

[Atharva-Kanherkar]

@claude can you tell me, if I use kaggles benchmarking system, it's in python, can I use it there? it seems like it's. a python plugin anyways?

[claude]

Claude finished @Atharva-Kanherkar's task in 39s —— View job

---

Can you use this SDK on Kaggle?

Short answer: Yes, technically — but with a few caveats worth knowing upfront.

---

What works

Kaggle notebooks run Python 3.10+ and support !pip install, so you can install the package directly:

# In a Kaggle notebook cell
!pip install git+https://github.com/agentclash/agentic-memory.git

(It's not on PyPI yet, so you'd pull from GitHub or upload the files manually.)

Once installed, the import just works:

from agentic_memory import Memory
m = Memory()
m.remember("some fact")

---

Caveats

1. You'll need a Google API key

The package depends on google-genai for embeddings (google-genai==1.68.0). That requires a GEMINI_API_KEY (or equivalent). On Kaggle, add it as a Kaggle Secret and expose it as an environment variable in your notebook settings — otherwise the SDK will fail to initialize.

2. ChromaDB persistence is ephemeral

chromadb (the vector store) writes to disk by default. In Kaggle's notebook environment, the disk is wiped between sessions. If you're benchmarking across multiple runs, you'll either need to:

• Re-populate memory at the start of each run, or
• Mount a Kaggle Dataset as the ChromaDB storage path

3. It's not a Kaggle "plugin" — it's a standard Python package. It works anywhere Python runs, including Kaggle notebooks. There's nothing Kaggle-specific about it.

4. chromadb install on Kaggle can be slow — it pulls several heavy native dependencies. Budget a minute or two for the install cell.

---

Minimum setup for a Kaggle notebook

import os
os.environ["GEMINI_API_KEY"] = "your-key-here"  # or use Kaggle Secrets

!pip install -q git+https://github.com/agentclash/agentic-memory.git

from agentic_memory import Memory
m = Memory()

This should be enough to get remember() / recall() working in a benchmarking script.

---