hermes-ai-know 1.0.0

AI KNOW - Memory Kernel for long-running AI agents (Hermes ecosystem)

AI KNOW - Python MVP

Python 3.11 + FastAPI implementation of the AI KNOW Memory Kernel v0.1. This is the primary execution path for v0.1; the Rust code under src/backend/memory-core/ is retained as a reference implementation.

Layout

python-mvp/
├── ai_know/
│   ├── main.py          # FastAPI app factory
│   ├── config.py        # Pydantic Settings (env-driven)
│   ├── api/             # HTTP routers (health, events, memories, ...)
│   ├── core/            # Ingestor, extractor, arbitrator, ...   (PR 3+)
│   ├── db/              # SQLAlchemy models + repositories       (PR 2)
│   ├── schemas/         # Pydantic request/response schemas       (PR 3+)
│   ├── providers/       # Embedding + LLM providers               (PR 4+)
│   └── jobs/            # Background jobs (dream, consolidation)  (PR 7+)
├── migrations/          # Alembic                                  (PR 2)
├── tests/
│   ├── unit/            # No I/O
│   ├── integration/     # Needs Postgres / Redis                    (PR 2+)
│   └── evals/           # Mini evals                                 (PR 8)
├── requirements.txt
├── pyproject.toml
├── Dockerfile
└── README.md

Quick start

From the ai-know repo root:

docker compose up --build
# One-shot: apply the schema.
docker compose exec api alembic upgrade head
curl http://localhost:8090/health
# → {"status":"ok","version":"0.1.0","environment":"dev"}
curl http://localhost:8090/health/ready
# → {"status":"ok",...,"database":"ok","redis":"ok"}

Host ports: API 8090, Postgres 5433, Redis 6380 (they coexist with Hermes on 8080/5432 and Claudio on 3001).

Local dev (no Docker)

cd src/backend/python-mvp
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL=postgresql+psycopg://ai_know:ai_know_dev@localhost:5433/ai_know
export REDIS_URL=redis://localhost:6380/0
alembic upgrade head
uvicorn ai_know.main:app --reload --port 8080

Tests

Unit only (no I/O):

pytest tests/unit -v

Integration (needs docker compose up):

# From inside the running api container:
docker compose exec api python -m pytest tests/integration -v

PR status (as of v0.1.0 tag)

PR	Scope	Status	Tests
1	scaffold / FastAPI / health	✅ done	–
2	DB migrations (9 tables + repos)	✅ done	14/14
3	Events API	✅ done	44/44
4	Episode + Claim extraction	✅ done	82/82
5	Arbitration + consolidation	✅ done	109/109
6	Context Pack builder	✅ done	149/149
7	Feedback engine	✅ done	174/174
8	Mini evals	✅ done	178/178
9	Hermes adapter (dogfooding)	✅ done	187/187
10	v0.1 release polish	✅ done	187/187

v0.1 backend RELEASE-READY. See the top-level CHANGELOG.md for landing dates and commits. See ai_know/adapters/hermes.py for the client-side SDK that lets hermes-agent (and any other host) talk to this backend without reimplementing the wire contract.