# Agents Database in System V1

`agents-database` is the durable store for System V1.

Canonical topology and machine bootstrap live in `~/personal-agent/docs/system-v1.md`.

## V1 Role

- canonical shared DB for memories, operational tasks, task runs, approvals, artifacts, and handoffs
- resumability anchor for multi-repo work
- migration target for legacy `personal-agent` state
- authoritative place to implement memory promotion, consolidation, and conflict handling

## Resume From Shared DB

Use the local CLI against `data/shared-agent-memory.sqlite3`:

```bash
python3 -m shared_agent_memory.cli --db data/shared-agent-memory.sqlite3 task-bundle task_<id>
python3 -m shared_agent_memory.cli --db data/shared-agent-memory.sqlite3 list-memories \
  --source-ref personal-agent:run:<run-id>
```

## Runtime Dependencies

- the configured CLI runner must be available for LLM consolidation steps (MiniMax M2.5 Free).
- local verification tools live in `./.venv` for this repo

## Memory pipeline

The memory pipeline lives in `MemoryService` / `MemoryEngine`, not in repo-local side scripts.

Current behavior:

- `ingest()` accepts durable memory writes
- `capture_session()` and `capture_conversation()` create raw source material
- `process_pending()` turns pending ingestion events into episode memories
- `consolidate_candidates(config)` handles dedup, conflict detection, promotion, and optional synthesis
- `maintenance_jobs` + `maintenance_runs` drive scheduled consolidation
- opportunistic checks run on startup and after writes

Promotion and conflict semantics:

- `episode` and `inbox` records are candidates, not truth by default
- exact duplicates are linked and archived
- conflicting claims produce explicit `memory_conflicts` rows and `contradicts` links
- inbox memories can be promoted to `active` once they pass the configured threshold
- the canonical output is always the shared DB record, not an external report

## Maintenance

```bash
.venv/bin/python -m shared_agent_memory.cli --db data/shared-agent-memory.sqlite3 maintenance-status
.venv/bin/python -m shared_agent_memory.cli --db data/shared-agent-memory.sqlite3 maintenance-tick --limit 10
.venv/bin/python -m shared_agent_memory.cli --db data/shared-agent-memory.sqlite3 maintenance-daemon --interval-seconds 900
```

Versioned service definitions:

- `systemd/user/agents-database-maintenance.service`
- `scripts/run-maintenance-daemon.sh`

Installed Linux user service:

- `~/.config/systemd/user/agents-database-maintenance.service`
- enabled with `systemctl --user enable --now agents-database-maintenance.service`
- `Restart=always` with `RestartSec=10`
- `loginctl show-user sebas --property=Linger` is `yes`, so the user service is eligible to come back after reboot without an interactive login

Operational checks:

```bash
systemctl --user status agents-database-maintenance.service --no-pager
systemctl --user show agents-database-maintenance.service --property=NRestarts,ExecMainPID,SubState
journalctl --user -u agents-database-maintenance.service -n 50 --no-pager
```

macOS launchd template:

- `docs/launchd/agents-database-maintenance.plist`

Current Linux runtime notes:

- the daemon now starts through `scripts/run-maintenance-daemon.sh`
- the wrapper exports `PYTHONPATH` for the repo checkout and prefers `./.venv/bin/python` when present
- the service was verified to auto-restart after a manual `systemctl --user kill agents-database-maintenance.service`
- `MemoryService` also performs opportunistic catch-up checks on startup and after normal write operations, so due jobs do not depend exclusively on the long-lived daemon

## Boundary

- new durable work: shared DB only
- legacy `~/personal-agent/data/personal-agent.sqlite3`: transition-only inspection and migration source

## RFCs

- `docs/memory-consolidation-rfc.md`