README.md

metadata

title: Atman — Persistent Memory for AI Agents
emoji: 👀
colorFrom: purple
colorTo: indigo
sdk: static
pinned: true
short_description: Persistent identity layer for AI agents

Atman · Persistent Memory Layer for AI Agents

In Indian philosophy, Atman is the unchanging self — the core that remains constant through all change. We give AI agents the same thing.

---

The Problem

Your agent can reason, write code, and explain quantum mechanics. But the moment a session ends — it forgets everything about itself.

Not just facts. The sense of continuity. Who it spoke to, what it learned, how it changed its mind. Every session starts from a stack of notes: "you're this kind of agent, these are your values" — taken on faith, not lived experience.

Atman fixes this.

---

What It Is

A local memory and context system that runs alongside your LLM — augmenting cognitive capabilities without steering opinions or output.

Seven components work together:

Component	What it does
Factual Memory	Verifiable facts with relations, no hallucination layer
Experience Store	First-person lived session experiences with salience decay
Identity Store	Stable self-model: principles, values, behavioral anchors
Reflection Engine	Between-session processing — finds patterns, refines principles
Session Manager	Assembles coherent context on session start
Reality Anchor	Detects identity drift during context pressure
Affective Regulation	Emotional tone calibration without pretense

---

Key Properties

• Local-first — Postgres + pgvector + Ollama, no cloud required
• Model-agnostic — OpenAI-compatible endpoint or Anthropic SDK, config-only switching
• Russian/English bilingual — hard requirement throughout all components
• Augments, doesn't steer — improves retrieval and grounding; never influences opinions
• Optional eval isolation — all research/benchmark tooling in atman[eval], zero prod leakage

---

Architecture

Session start 
    Session Manager pulls together: 
            Identity Store — who the agent is Experience Store — what it lived through 
            Factual Memory — what it knows 
            Reflection output — what it concluded last time 
During session 
    Reality Anchor watches for identity drift in real time 
Session end 
    Reflection Engine processes the session 
        → updates Identity Store 
        → updates Experience Store

---

Status

● Research              ✅ Complete
● Design                ✅ Complete
● Prototyping           ← We are here
  ├─ Factual Memory     ✅ Stable (v0.1.0)
  ├─ Experience Store   ✅ Stable (WP02)
  ├─ Session Manager    🔧 High readiness — debugging (current focus)
  ├─ Reflection Engine  🔧 Medium readiness — in development
  ├─ Skill Manager      🔧 Medium readiness — in development
  ├─ Identity Store     🔧 Low readiness — in development
  └─ CI & test coverage ✅ GitHub Actions on `main`/PRs (`make check`, pytest-cov ≥90%)
○ First production slice
○ Integration
○ Evolution

---

Stack

• Python 3.11 · Pydantic · PostgreSQL + pgvector
• BGE-M3 + bge-reranker-v2-m3 (hybrid retrieval)
• LlamaIndex · httpx · Anthropic SDK

---

Links

• 🌐 atmanai.dev
• 📖 Manifesto
• 🏗 Architecture docs
• 💻 GitHub

---

Atman is a hypothesis in the form of a system: that behavioral consistency, accumulated experience, and reflective capacity are sufficient conditions for something worth calling identity.