soul-memory

Memory belongs to the user, not to the model.

soul-memory is a model-independent, local-first Memory Operating System for AI Agents.

It is designed to help AI agents understand users across sessions while keeping memory owned, exportable and controllable by the user.

Core Idea

Models should not own user memory.

Instead, GPT, Claude, Codex, Gemini, Cursor, OpenClaw and future agents should all be able to consume the same user-owned memory layer through adapters.

AI Agent
   |
Adapter
   |
Memory API
   |
Retrieval Engine
   |
Memory Engine
   |
User-Owned Memory Store

Current Version

v0.7.3 is the current Session Assembler release for the local MVP.

It contains:

• Vision documents
• Architecture documents
• Concept definitions
• RFCs
• MVP implementation specification
• Pydantic API schemas
• Memory detail and statistics endpoints
• Consistent runtime error handling
• Codex CLI adapter
• Portable JSON memory import
• Memory schema v0.2 with subtype and migration support
• Import normalization for legacy and external memory types
• Controlled soul sync memory write path
• Soul Event Protocol v1 domain model
• Durable SQLite event store
• Event ingest/list/show API
• Event CLI inspection tools
• Codex lifecycle hook connector
• Codex event delivery spool
• Safe soul connect codex hook installation
• Deterministic Session Assembler for reconstructing conversation sessions and turns

MVP Goal

Build a local memory service that proves cross-session memory:

1. Store durable user information.
2. Start a new session.
3. Recall relevant user memory.
4. Inject concise context into an AI agent.

Run the MVP

Install dependencies:

pip install -e .[dev]

Start the local service:

python -m uvicorn src.main:app --host 127.0.0.1 --port 8765

The default SQLite database is soul_memory.db in the current working directory. Override it with SOUL_MEMORY_DB.

Example PowerShell flow:

Invoke-RestMethod http://localhost:8765/memories `
  -Method Post `
  -ContentType "application/json" `
  -Body '{"type":"project","content":"User is building soul-memory.","importance":5}'

Invoke-RestMethod http://localhost:8765/recall `
  -Method Post `
  -ContentType "application/json" `
  -Body '{"query":"Help me continue this project."}'

Invoke-RestMethod http://localhost:8765/export

v0.4.1 also includes:

Invoke-RestMethod http://localhost:8765/memories/{memory_id}
Invoke-RestMethod http://localhost:8765/stats

Invalid memory types return HTTP 400 with a clear error message. Malformed request payloads return HTTP 422.

Soul Event Protocol

v0.7.1 adds a source-independent event ingestion layer. Events are observations, not memories, and do not automatically write active memories.

API endpoints:

POST /events
GET /events
GET /events/{event_id}

CLI examples:

node bin/soul.mjs event ingest event.json
node bin/soul.mjs events --session session-demo
node bin/soul.mjs events --type user.prompt --source demo-agent
node bin/soul.mjs event show demo-001

Re-ingesting the same event_id is idempotent and reports duplicate=true.

Codex Event Connector

v0.7.2 connects selected Codex lifecycle hooks to the Soul Event Protocol:

SessionStart -> session.started
UserPromptSubmit -> user.prompt
Stop -> agent.response

Install the user-level hooks:

node bin/soul.mjs connect codex

Then open Codex, run /hooks, and review/trust the Soul Memory hook definitions.

Inspect connector state and replay offline events:

node bin/soul.mjs connector codex status
node bin/soul.mjs connector codex flush
node bin/soul.mjs disconnect codex

The connector stores failed deliveries as normalized SoulEvent JSON under ~/.soul/spool/codex/. It captures user prompts, latest assistant responses at Stop, session/workspace context, and selected model/permission metadata. It does not parse Codex transcripts and does not implement secret redaction.

Session Assembler

v0.7.3 reconstructs inspectable conversation sessions from stored SoulEvents:

Event Store -> Session Assembler -> ConversationSession -> ConversationTurn

It groups events by source and native session.id, orders them by occurred_at with insertion order as the tie breaker, and pairs user.prompt with agent.response. Missing responses are preserved as incomplete turns. It does not create memory candidates, run LLM extraction, or write memories automatically.

API endpoints:

GET /sessions
GET /sessions/{session_id}

CLI examples:

node bin/soul.mjs sessions
node bin/soul.mjs session show session-demo

Codex CLI Adapter

The v0.6.0 CLI adapter connects Codex to soul-memory without modifying Codex.

Initialize local CLI config:

node bin/soul.mjs init

Check status:

node bin/soul.mjs status

Recall memory:

node bin/soul.mjs recall "continue this project"

Run Codex with generated context:

node bin/soul.mjs codex "implement the next task"

This generates:

.soul/context.md
AGENTS.md

Use --dry-run to generate files without launching Codex:

node bin/soul.mjs codex "implement the next task" --dry-run

Sync candidate memories from a coding session:

node bin/soul.mjs sync --summary "Implemented the Codex CLI adapter"

The sync command shows candidates and asks for confirmation before storing anything.

Import portable memory JSON:

node bin/soul.mjs import soul-memory-guolin-profile-v0.1.json

Use --preview to inspect normalization and duplicate handling without storing memories:

node bin/soul.mjs import soul-memory-guolin-profile-v0.1.json --preview

Use --yes to skip the confirmation prompt after preview:

node bin/soul.mjs import soul-memory-guolin-profile-v0.1.json --yes

Clear memories for the configured user:

node bin/soul.mjs clear

For scripted reset:

node bin/soul.mjs clear --yes

Clear another user or all users:

node bin/soul.mjs clear --user guolin
node bin/soul.mjs clear --all

clear permanently deletes memories and memory events. Use it when you want a clean import environment.

Repository Layout

docs/
  vision/
  architecture/
  concepts/
  rfc/
  implementation/

src/
  api/
  memory/
  extraction/
  retrieval/
  injection/
  adapter/

examples/
tests/
scripts/