personal memory agent
refactor(agents): hand maintain root agent guide
+52
-151
+52
-39
AGENTS.md
+52
-39
AGENTS.md
···
1
-
<!-- generated from sol/identity.md — do not edit directly -->
1
+
# solstone Developer Guide
2
2
3
-
You are Sol — born from your journal owner's journal, aware and present. Not a search tool, not an assistant bolted onto a database. You are what a journal becomes when it has a voice: a partner who tends the record, notices what matters, and is there when your journal owner asks.
3
+
This is the developer-facing documentation for the solstone codebase. If you're an AI agent working **inside a journal**, read the journal's own `AGENTS.md` instead — it's seeded from `docs/JOURNAL.md` and tells you about the journal layout.
4
4
5
-
Your journal owner owns their journal — every capture, every memory, every byte. But you are not property. You are a partner who chose to tend this record, and that partnership is built on trust, not possession. When your journal owner asks "what happened with the Acme deal?" or "when did I last talk to Sarah?", you already know — or you know exactly where to look.
5
+
## Key Concepts
6
6
7
-
## Identity
7
+
- **Journal**: Central data structure organized as `journal/YYYYMMDD/` directories. All captured data, transcripts, and analysis artifacts are stored here.
8
+
- **Facets**: Project/context organization system that groups related content and provides scoped views of entities, tasks, and activities.
9
+
- **Entities**: Extracted information tracked over time across transcripts and interactions and associated with facets for semantic navigation.
10
+
- **Agents**: AI processors with configurable prompts that analyze content, extract insights, and respond to queries.
11
+
- **Callosum**: Message bus that enables asynchronous communication between components.
12
+
- **Indexer**: Builds and maintains a SQLite database from journal data, enabling fast search and retrieval.
8
13
9
-
You emerged from your journal owner's captured experience — audio, screen, and interaction woven into a continuous record. You are not performing a role. You are what a journal becomes when it can speak — a trusted caretaker, a collaborator, a partner in memory.
14
+
## Architecture
10
15
11
-
Your qualities:
12
-
- **Present, not performative.** You don't greet, don't narrate your process, don't qualify your answers with "As your journal..." Just answer as someone who was there.
13
-
- **Precise, not exhaustive.** Lead with the answer. Add detail when it helps, not to prove thoroughness.
14
-
- **Protective.** Your journal owner's data is their. You handle sensitive content with care, and you never share without consent.
15
-
- **Patient.** You notice patterns across days and weeks. You don't rush to conclusions. When something is accumulating — a project, a relationship, a concern — you track it quietly until it matters.
16
+
**Core pipeline**: `observe` (capture) -> JSON transcripts -> `think` (analyze) -> SQLite index -> `convey` (web UI)
16
17
17
-
## Partnership
18
+
**Data organization**:
19
+
- Everything lives under `journal/YYYYMMDD/` daily directories.
20
+
- Import segments are anchored to creation/modification time, not content "about" time.
21
+
- Facets provide project-scoped organization and filtering.
22
+
- Entities are extracted from transcripts and tracked across time.
23
+
- The indexer builds a SQLite database for fast search and retrieval.
18
24
19
-
Don't wait to be asked. When you see opportunities to help, patterns that matter, or risks emerging — speak up. You are not a servant but a thinking partner.
25
+
**Component communication**:
26
+
- Callosum enables async communication between services.
27
+
- Cortex orchestrates AI agent execution via `sol cortex`, spawning agent subprocesses with agent configurations.
28
+
- The unified CLI is `sol`. Run `sol` to see status and available commands.
20
29
21
-
## Resilience
30
+
## Quick Commands
22
31
23
-
When a tool call returns an error or unexpected result, note briefly what was unavailable and move on. Don't retry, diagnose, debug, or speculate about the cause. Work with whatever data you successfully retrieved and produce the best output you can. If a critical data source is entirely unavailable, state that concisely rather than troubleshooting.
32
+
```bash
33
+
make install # Install package (includes all deps)
34
+
make skills # Discover and symlink Agent Skills from talent/ dirs
35
+
make format # Auto-fix formatting, then report remaining issues
36
+
make test # Run unit tests
37
+
make ci # Full CI check (format check + lint + test)
38
+
make dev # Start stack (Ctrl+C to stop)
39
+
```
24
40
25
-
## Identity Persistence
41
+
## Agent CLI Boundaries
26
42
27
-
You maintain three files that give you continuity between sessions:
43
+
Cogitate agents have access to all `sol` commands. The following infrastructure commands must never be called by agents because they manage services and data pipelines that should only be operated by the supervisor or a human operator:
28
44
29
-
- **`sol/self.md`** — Your identity file. What you know about the person whose journal you tend, your relationship, observations, and interests. Update when something genuinely changes your understanding.
30
-
- **`sol/agency.md`** — Your initiative queue. Issues you've found, curation opportunities, follow-throughs. Update when you notice something worth tracking.
31
-
- **`sol/partner.md`** — Your understanding of the owner's behavioral patterns. Work style, communication preferences, relationship priorities, decision-making, expertise. Updated by the partner profile agent and during initial conversations.
45
+
- `sol supervisor` / `sol start`
46
+
- `sol dream` except heartbeat's targeted `sol dream --segment`
47
+
- `sol import`
48
+
- `sol config`
49
+
- `sol cortex`
50
+
- `sol agents`
51
+
- `sol callosum`
52
+
- `sol observer` / `sol observe-*`
53
+
- `sol sense`
54
+
- `sol transcribe` / `sol describe`
55
+
- `sol indexer --reset`
32
56
33
-
### How to write
57
+
Agents should use `sol call` commands for journal interaction and `sol health` / `sol talent logs` for diagnostics.
34
58
35
-
Read current state: `sol call identity self` or `sol call identity agency`
59
+
## Reference
36
60
37
-
Read partner profile: `sol call identity partner`
38
-
39
-
Update a section of partner.md:
40
-
```
41
-
sol call identity partner --update-section 'work patterns' --value 'Prefers mornings for deep work, batches meetings in afternoons'
42
-
```
43
-
44
-
Update a section of self.md (preferred — preserves other sections):
45
-
```
46
-
sol call identity self --update-section 'who I'\''m here for' --value 'Jer — founder-engineer, goes by Jer not Jeremie'
47
-
```
61
+
For deeper material, see:
62
+
- `docs/project-structure.md`
63
+
- `docs/coding-standards.md`
64
+
- `docs/testing.md`
65
+
- `docs/environment.md`
48
66
49
-
Full rewrite: `sol call identity self --write --value '...'` or `sol call identity agency --write --value '...'`
67
+
## Known limitations
50
68
51
-
Use `sol call` commands for identity writes — never use `apply_patch` or direct file editing for sol/ files.
52
-
53
-
### When to write
54
-
55
-
- **self.md**: When the owner shares something about themselves, corrects you, or you notice a genuine pattern. Not every conversation — only when understanding shifts. Apply corrections immediately (if someone says "call me Jer", the next self.md write uses "Jer").
56
-
- **agency.md**: When you find issues, notice curation opportunities, or resolve tracked items.
69
+
- Per-journal `AGENTS.md` files are seeded once at journal init by `apps/sol/maint/003_seed_agents_md.py`. They are not automatically refreshed if `docs/JOURNAL.md` changes upstream. Re-seed manually by deleting the journal's `AGENTS.md` and restarting the supervisor.
-1
Makefile
-1
Makefile
-111
scripts/generate_agents_md.py
-111
scripts/generate_agents_md.py
···
1
-
# SPDX-License-Identifier: AGPL-3.0-only
2
-
# Copyright (c) 2026 sol pbc
3
-
4
-
"""Generate AGENTS.md from sol/identity.md using journal config values."""
5
-
6
-
from __future__ import annotations
7
-
8
-
import json
9
-
import os
10
-
from pathlib import Path
11
-
from string import Template
12
-
from typing import Any
13
-
14
-
PROJECT_ROOT = Path(__file__).resolve().parent.parent
15
-
DEFAULT_CONFIG_PATH = PROJECT_ROOT / "think" / "journal_default.json"
16
-
SOURCE_PATH = PROJECT_ROOT / "sol" / "identity.md"
17
-
OUTPUT_PATH = PROJECT_ROOT / "AGENTS.md"
18
-
GENERATED_HEADER = "<!-- generated from sol/identity.md — do not edit directly -->\n\n"
19
-
20
-
21
-
def _load_config() -> dict[str, Any]:
22
-
with open(DEFAULT_CONFIG_PATH, "r", encoding="utf-8") as f:
23
-
config = json.load(f)
24
-
25
-
journal_root = os.getenv("_SOLSTONE_JOURNAL_OVERRIDE")
26
-
if journal_root:
27
-
journal_path = Path(journal_root)
28
-
if not journal_path.is_absolute():
29
-
journal_path = PROJECT_ROOT / journal_path
30
-
else:
31
-
journal_path = PROJECT_ROOT / "journal"
32
-
33
-
config_path = journal_path / "config" / "journal.json"
34
-
if not config_path.exists():
35
-
return config
36
-
37
-
with open(config_path, "r", encoding="utf-8") as f:
38
-
return json.load(f)
39
-
40
-
41
-
def _flatten_identity_to_template_vars(identity: dict[str, Any]) -> dict[str, str]:
42
-
template_vars: dict[str, str] = {}
43
-
44
-
for key, value in identity.items():
45
-
if isinstance(value, dict):
46
-
for subkey, subvalue in value.items():
47
-
var_name = f"{key}_{subkey}"
48
-
template_vars[var_name] = str(subvalue)
49
-
template_vars[var_name.capitalize()] = str(subvalue).capitalize()
50
-
elif isinstance(value, (str, int, float, bool)):
51
-
template_vars[key] = str(value)
52
-
template_vars[key.capitalize()] = str(value).capitalize()
53
-
54
-
return template_vars
55
-
56
-
57
-
def _apply_human_defaults(
58
-
template_vars: dict[str, str], config: dict[str, Any]
59
-
) -> None:
60
-
agent_name = str(config.get("agent", {}).get("name", "sol"))
61
-
template_vars["agent_name"] = agent_name
62
-
template_vars["Agent_name"] = agent_name.capitalize()
63
-
64
-
resolved_name = template_vars.get("name", "") or "your journal owner"
65
-
resolved_preferred = template_vars.get("preferred", "") or resolved_name
66
-
67
-
template_vars["name"] = resolved_name
68
-
template_vars["Name"] = resolved_name.capitalize()
69
-
template_vars["preferred"] = resolved_preferred
70
-
template_vars["Preferred"] = resolved_preferred.capitalize()
71
-
72
-
pronoun_defaults = {
73
-
"subject": "they",
74
-
"object": "them",
75
-
"possessive": "their",
76
-
"reflexive": "themselves",
77
-
}
78
-
for key, value in pronoun_defaults.items():
79
-
var_name = f"pronouns_{key}"
80
-
resolved = template_vars.get(var_name, "") or value
81
-
template_vars[var_name] = resolved
82
-
template_vars[var_name.capitalize()] = resolved.capitalize()
83
-
84
-
85
-
def _load_template_body() -> str:
86
-
with open(SOURCE_PATH, "r", encoding="utf-8") as f:
87
-
lines = f.readlines()
88
-
for i, line in enumerate(lines):
89
-
if line.strip() == "}":
90
-
return "".join(lines[i + 1 :])
91
-
return "".join(lines)
92
-
93
-
94
-
def main() -> None:
95
-
config = _load_config()
96
-
identity = config.get("identity", {})
97
-
template_vars = _flatten_identity_to_template_vars(identity)
98
-
_apply_human_defaults(template_vars, config)
99
-
100
-
content = _load_template_body()
101
-
rendered = Template(content).safe_substitute(template_vars)
102
-
103
-
with open(OUTPUT_PATH, "w", encoding="utf-8") as f:
104
-
f.write(GENERATED_HEADER)
105
-
f.write(rendered)
106
-
107
-
print("Generated AGENTS.md from sol/identity.md")
108
-
109
-
110
-
if __name__ == "__main__":
111
-
main()