agent-memory-forest 1.0.0b1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agent_memory_forest-1.0.0b1.dist-info/METADATA +358 -0
- agent_memory_forest-1.0.0b1.dist-info/RECORD +74 -0
- agent_memory_forest-1.0.0b1.dist-info/WHEEL +5 -0
- agent_memory_forest-1.0.0b1.dist-info/entry_points.txt +6 -0
- agent_memory_forest-1.0.0b1.dist-info/licenses/LICENSE +21 -0
- agent_memory_forest-1.0.0b1.dist-info/top_level.txt +1 -0
- memory_forest/__init__.py +74 -0
- memory_forest/__main__.py +4 -0
- memory_forest/adapters/__init__.py +143 -0
- memory_forest/adapters/common.py +347 -0
- memory_forest/adapters/jsonl.py +216 -0
- memory_forest/agents.py +449 -0
- memory_forest/archive.py +639 -0
- memory_forest/audit.py +287 -0
- memory_forest/checks.py +91 -0
- memory_forest/cli.py +868 -0
- memory_forest/cli_find.py +585 -0
- memory_forest/cli_intake.py +172 -0
- memory_forest/cli_setup.py +148 -0
- memory_forest/cli_upkeep.py +287 -0
- memory_forest/collections.py +1004 -0
- memory_forest/config.py +1028 -0
- memory_forest/core.py +1085 -0
- memory_forest/credential_ledger.py +334 -0
- memory_forest/credentials.py +998 -0
- memory_forest/derived.py +1063 -0
- memory_forest/doctor.py +273 -0
- memory_forest/embeddings.py +40 -0
- memory_forest/errors.py +549 -0
- memory_forest/forest.py +8 -0
- memory_forest/groups.py +1202 -0
- memory_forest/guide/contract.md +1305 -0
- memory_forest/guide/routine.md +292 -0
- memory_forest/guide/setup.md +164 -0
- memory_forest/guide/use.md +52 -0
- memory_forest/index.py +502 -0
- memory_forest/intake.py +2215 -0
- memory_forest/journal.py +181 -0
- memory_forest/layout.py +593 -0
- memory_forest/leaving.py +115 -0
- memory_forest/letters/cyrillic.json +55 -0
- memory_forest/letters/greek.json +32 -0
- memory_forest/letters/hangul.json +73 -0
- memory_forest/letters/kana.json +283 -0
- memory_forest/letters/latin.json +48 -0
- memory_forest/levels.py +483 -0
- memory_forest/lint.py +1028 -0
- memory_forest/locking.py +359 -0
- memory_forest/maps.py +458 -0
- memory_forest/mcp.py +1413 -0
- memory_forest/model.py +1299 -0
- memory_forest/move.py +1554 -0
- memory_forest/movelog.py +308 -0
- memory_forest/names.py +324 -0
- memory_forest/numbers.py +410 -0
- memory_forest/phrases/ko.json +42 -0
- memory_forest/plan.py +1308 -0
- memory_forest/record.py +619 -0
- memory_forest/registry.py +880 -0
- memory_forest/repeats.py +531 -0
- memory_forest/retrieval.py +839 -0
- memory_forest/safety.py +480 -0
- memory_forest/scope.py +81 -0
- memory_forest/search.py +3153 -0
- memory_forest/setup_agent.py +521 -0
- memory_forest/sources.py +250 -0
- memory_forest/stage.py +108 -0
- memory_forest/system.py +1712 -0
- memory_forest/timeline.py +556 -0
- memory_forest/tool_commands.py +234 -0
- memory_forest/turn_keys.py +101 -0
- memory_forest/validate.py +264 -0
- memory_forest/view.py +194 -0
- memory_forest/writer.py +2863 -0
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-memory-forest
|
|
3
|
+
Version: 1.0.0b1
|
|
4
|
+
Summary: A readable, rule-kept local memory for long-running AI agents and teams of agents
|
|
5
|
+
Author: Hyungchul Choi
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/hyungchulc/agent-memory-forest
|
|
8
|
+
Project-URL: Repository, https://github.com/hyungchulc/agent-memory-forest
|
|
9
|
+
Project-URL: Issues, https://github.com/hyungchulc/agent-memory-forest/issues
|
|
10
|
+
Keywords: agents,ai-memory,knowledge-management,local-first,provenance,retrieval,sqlite
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Database :: Database Engines/Servers
|
|
21
|
+
Classifier: Topic :: Text Processing :: Indexing
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Dynamic: license-file
|
|
26
|
+
|
|
27
|
+
# Agent Memory Forest
|
|
28
|
+
|
|
29
|
+
**A readable, rule-kept local memory for long-running AI agents and teams of agents.**
|
|
30
|
+
|
|
31
|
+
**English** · [한국어](README.ko.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md)
|
|
32
|
+
|
|
33
|
+
[](https://github.com/hyungchulc/agent-memory-forest/actions/workflows/ci.yml)
|
|
34
|
+
[](https://www.python.org/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
[](docs/privacy-and-trust.md)
|
|
37
|
+
|
|
38
|
+
Agent Memory Forest is a Python package and a `forest` command that keep what agents learn as plain
|
|
39
|
+
Markdown pages in a few numbered folders on your own disk. Every fact has one home, decided by rules rather
|
|
40
|
+
than by the chat or the agent that brought it in, and code, not a model, decides where a page belongs and
|
|
41
|
+
when a subject has grown enough to get pages of its own.
|
|
42
|
+
|
|
43
|
+
**Status:** version `1.0.0b1`, a beta: the first public release of version 1. The 0.3 `memory-forest`
|
|
44
|
+
command stays installed beside it ([archive](docs/archive-0.3/cli.md)).
|
|
45
|
+
|
|
46
|
+
> [!IMPORTANT]
|
|
47
|
+
> Agent Memory Forest is not a hosted service, an authorization system, or a promise that an agent will
|
|
48
|
+
> remember correctly. Memory is grounding data: a caller still opens the page it was routed to, checks how
|
|
49
|
+
> fresh it is, and applies its own authority and safety rules. The forest holds no credentials, and
|
|
50
|
+
> everything except optional vector search works with no network.
|
|
51
|
+
|
|
52
|
+
## Start here
|
|
53
|
+
|
|
54
|
+
You need Python 3.11 or newer and a POSIX filesystem; there are no runtime dependencies outside the
|
|
55
|
+
standard library. On Windows, use WSL2 and keep the forest on the Linux filesystem; read the
|
|
56
|
+
[WSL2 guide](docs/wsl2.md) first. The package is on no package index. Install it from the repository's
|
|
57
|
+
address:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
python -m pip install "git+https://github.com/hyungchulc/agent-memory-forest"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
or from a clone, with `python -m pip install .` in its folder. `forest --version` checks the install;
|
|
64
|
+
where the `forest` command is not on the path, `python -m memory_forest.forest` is the same command. Then
|
|
65
|
+
say one sentence to your agent:
|
|
66
|
+
|
|
67
|
+
> Run `forest guide` and follow it.
|
|
68
|
+
|
|
69
|
+
The agent connects itself. It runs `forest setup`, which hands it the questions to ask you, and asks you
|
|
70
|
+
each of them: where the forest lives, the agent's name, whether it is your main agent, which conversations
|
|
71
|
+
come in, and who keeps the forest growing. Every question that is yours to answer comes to you; the agent
|
|
72
|
+
never answers one itself. It then sets the forest up or joins the one you named, registers the finding
|
|
73
|
+
server in its own tool, brings its own conversation in, and proves the result with `forest doctor`.
|
|
74
|
+
|
|
75
|
+
## What you get
|
|
76
|
+
|
|
77
|
+
- **The forest and its rules.** Numbered folders of plain pages, and one contract every forest keeps:
|
|
78
|
+
[contract](docs/contract.md), explained for a new reader in [concepts](docs/concepts.md).
|
|
79
|
+
- **The structure tools.** `forest init`, `registry`, `move`, `levels`, `collections`, `record`,
|
|
80
|
+
`archive`, `check`, `lint`, `numbers`, `credentials` and `recover`: [tools](docs/tools.md).
|
|
81
|
+
- **Finding.** `forest search`, `read`, `timeline` and `navigate` as commands, and `forest mcp`, an MCP
|
|
82
|
+
server with five tools (`memory_search`, `memory_read`, `memory_timeline`, `memory_navigate`,
|
|
83
|
+
`memory_log`): [tools](docs/tools.md#forest-mcp).
|
|
84
|
+
- **Two write doors.** `forest log` or `memory_log` for an agent's own turn, and records in the lane's
|
|
85
|
+
shape, read by `forest intake --from jsonl`: [tools](docs/tools.md#forest-intake).
|
|
86
|
+
- **A tree per agent.** Shared trees for what everyone needs, a tree of its own for each agent, and reader
|
|
87
|
+
scopes: [agents](docs/multi-agent.md).
|
|
88
|
+
- **The guide, setup and doctor.** `forest guide` (setup, routine, use, contract), `forest setup` and
|
|
89
|
+
`forest doctor`: [connecting an agent](docs/setup.md) and [tools](docs/tools.md#forest-guide).
|
|
90
|
+
|
|
91
|
+
## What it does not do
|
|
92
|
+
|
|
93
|
+
- **It reads no particular agent program's transcripts.** Every program keeps its conversation in its own
|
|
94
|
+
format, and the package cannot keep up with all of them; shipping readers for a few would promise what it
|
|
95
|
+
cannot keep. Your agent knows its own program: following the guide, it writes a small exporter that
|
|
96
|
+
appends its turns as records. Someone who knows a program well can write a reader for it
|
|
97
|
+
([adapters](docs/adapters.md)).
|
|
98
|
+
- **It has no engine and no timer.** The daily record, the filing run and the upkeep run are carried out by
|
|
99
|
+
your agent, on its own schedule and with its own model, following `forest guide routine`. The package is
|
|
100
|
+
the judge: `forest check`, `forest lint`, `forest levels` and `forest doctor`.
|
|
101
|
+
- **It writes nothing into another program's settings**, and it has no plugins. Setup writes only inside
|
|
102
|
+
the forest's folder and tells the agent what to register in its own tool.
|
|
103
|
+
|
|
104
|
+
## By hand
|
|
105
|
+
|
|
106
|
+
Without an agent, the same path is a few commands. Setup with no answers lists the questions; with every
|
|
107
|
+
answer it writes the forest and prints its `todo`:
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
forest setup # next: ask_owner, and each question with its flag
|
|
111
|
+
forest setup --root studio-forest --as "Kiln Bot" --main yes --conversations all --earlier no \
|
|
112
|
+
--keeper this --when "every night at 23:30" --daily-model "small model" --filing-model "large model"
|
|
113
|
+
# next: done
|
|
114
|
+
# todo 1. register_mcp 2. bring_turns 3. own_turn 4. routine 5. verify, each with its command
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Carry out the `todo`: register `forest mcp --as kiln-bot --root studio-forest` in your MCP client, and
|
|
118
|
+
bring turns in with the printed `forest intake` command or with `forest log`. Then prove it:
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
forest doctor --as "Kiln Bot" --root studio-forest --phrase # prints a new phrase to say
|
|
122
|
+
forest log --as kiln-bot --root studio-forest <<'TURN'
|
|
123
|
+
Kiln Two fires to cone 5 for now. forest doctor phrase orchid maple amber
|
|
124
|
+
TURN
|
|
125
|
+
forest index build --root studio-forest
|
|
126
|
+
forest doctor --as "Kiln Bot" --root studio-forest # result: passed (exit 0), or todo (exit 1)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The phrase is new each time; bring in the one your doctor printed. The `finding` check passes once an MCP
|
|
130
|
+
client has called the server once; until then the doctor says `todo` and prints the `forest mcp` command to
|
|
131
|
+
register. With no MCP client the commands are the doors: add `--doors commands` to the doctor line, and
|
|
132
|
+
the search the doctor runs is the proof.
|
|
133
|
+
|
|
134
|
+
The answers hold. The agent that keeps the forest reads every agent's turns, so it is your main agent
|
|
135
|
+
(`--keeper this` with `--main no` is asked again). And when you answer `--conversations none` for an
|
|
136
|
+
agent, the forest itself refuses that agent's turns (`recording_off`), whatever exporter or hook still
|
|
137
|
+
runs.
|
|
138
|
+
|
|
139
|
+
## Documentation
|
|
140
|
+
|
|
141
|
+
| Document | What it covers |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| [Concepts](docs/concepts.md) | the forest for a new reader: layers, a subject's life, one home, what goes up, records, moves, the lint |
|
|
144
|
+
| [Contract](docs/contract.md) | every rule a forest keeps, stated once |
|
|
145
|
+
| [Connecting an agent](docs/setup.md) | what `forest setup` asks and writes, and what `forest doctor` proves |
|
|
146
|
+
| [Agents](docs/multi-agent.md) | agent trees, the two filing policies, reader scopes, the single writer |
|
|
147
|
+
| [Design](docs/v1-design.md) | the package: on-disk layout, settings, package map, milestones |
|
|
148
|
+
| [Tools](docs/tools.md) | `forest move`, `levels`, `collections`, `check`, `lint`, `record`, `numbers`, `intake`, `index`, `search`, `timeline`, `log`, `mcp`, `guide`, `setup` and `doctor` |
|
|
149
|
+
| [Writing a reader](docs/adapters.md) | a reader of one agent program's own transcripts, for someone who knows that program |
|
|
150
|
+
| `forest guide` | the setup guide: the steps an agent follows to connect itself |
|
|
151
|
+
| `forest guide routine` | the routine guide: the daily record, the filing run and the upkeep run, for the agent that keeps the forest |
|
|
152
|
+
| `forest guide use` | the use guide: when and how an agent looks things up |
|
|
153
|
+
| `forest guide contract` | the contract, as the installed package prints it |
|
|
154
|
+
| [Comparison](docs/comparison.md) | how this differs from Mem0, GBrain, the LLM Wiki idea and plain vector RAG |
|
|
155
|
+
| [Privacy and trust](docs/privacy-and-trust.md) | what stays local, what a reader can see, memory as untrusted data |
|
|
156
|
+
| [Roadmap](docs/roadmap.md) | the three milestones and what may come later |
|
|
157
|
+
| [WSL2](docs/wsl2.md) | running on Windows through WSL2 |
|
|
158
|
+
| [Archive of 0.3](docs/archive-0.3/) | the 0.3 documents that version 1 replaces |
|
|
159
|
+
|
|
160
|
+
The three guides and the contract ship inside the package (`src/memory_forest/guide/`) and those commands
|
|
161
|
+
print them, so an agent reads the copy that matches the version it has installed.
|
|
162
|
+
|
|
163
|
+
## Why this exists
|
|
164
|
+
|
|
165
|
+
A long-running agent tends to fail at memory in one of two ways: it keeps too little, or it keeps a pile
|
|
166
|
+
that grows until nothing in it can be found and nobody can correct it. Version 1 is built around a few
|
|
167
|
+
properties that address that directly.
|
|
168
|
+
|
|
169
|
+
- **The subject is the unit.** A person, a project, a device, an agent: each has one registry line with its
|
|
170
|
+
aliases, and its material lives in its own home.
|
|
171
|
+
- **Places are decided by code.** A subject's level (an entry on a shared page, a leaf, a branch, a tree)
|
|
172
|
+
follows the number of distinct days its material covers. Every move goes through one tool that rewrites
|
|
173
|
+
references and logs the move.
|
|
174
|
+
- **One home for each fact.** Other pages carry a dated reference line, not a copy, so facts cannot drift
|
|
175
|
+
apart.
|
|
176
|
+
- **History is kept.** A changed fact moves to the page's update record; long records are archived
|
|
177
|
+
verbatim; nothing is deleted.
|
|
178
|
+
- **Upper pages hold what is established.** A preference reaches a summary page only on repeated evidence
|
|
179
|
+
or the owner's own words, never because it is the newest thing said.
|
|
180
|
+
- **A linter with codes.** Every rule that has a shape is checked, and a run must clean up what it added
|
|
181
|
+
without being blocked by what was already there.
|
|
182
|
+
- **Built for several agents.** Raw lanes per agent, one writer at a time, reader scopes, and two filing
|
|
183
|
+
policies.
|
|
184
|
+
|
|
185
|
+
## The forest in one picture
|
|
186
|
+
|
|
187
|
+
```mermaid
|
|
188
|
+
flowchart TB
|
|
189
|
+
owner(["Owner"]) <--> hub["Orchestrator agent"]
|
|
190
|
+
hub <--> botA["Bot A"]
|
|
191
|
+
hub <--> botB["Bot B"]
|
|
192
|
+
|
|
193
|
+
subgraph lanes ["Lanes (not forest)"]
|
|
194
|
+
istm["06 istm<br/>one raw lane per agent, append-only"]
|
|
195
|
+
daily["05 daily<br/>one readable page per day"]
|
|
196
|
+
istm --> daily
|
|
197
|
+
end
|
|
198
|
+
|
|
199
|
+
hub -- append --> istm
|
|
200
|
+
botA -- append --> istm
|
|
201
|
+
botB -- append --> istm
|
|
202
|
+
|
|
203
|
+
daily -- "filing run<br/>one writer at a time" --> stm
|
|
204
|
+
|
|
205
|
+
subgraph forest ["Forest"]
|
|
206
|
+
xltm["01 xltm<br/>identity · trees · agents"]
|
|
207
|
+
subgraph shared ["Shared trees"]
|
|
208
|
+
ltm["02 ltm tree pages"] --> mtm["03 mtm indexes and boards"] --> stm["04 stm leaves"]
|
|
209
|
+
end
|
|
210
|
+
subgraph own ["Agent trees, one per agent"]
|
|
211
|
+
altm["role · instructions · lessons"] --> amtm["boards"] --> astm["runs · methods · hand-offs"]
|
|
212
|
+
end
|
|
213
|
+
xltm --> ltm
|
|
214
|
+
xltm --> altm
|
|
215
|
+
end
|
|
216
|
+
|
|
217
|
+
hub -. reads everything .-> forest
|
|
218
|
+
botA -. reads shared + own .-> shared
|
|
219
|
+
botB -. reads shared + own .-> shared
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Material moves up from the lanes into the leaves, and only what the leaves establish is carried up to the
|
|
223
|
+
boards and tree pages. Placement goes the other way: the root index says which tree a kind of subject
|
|
224
|
+
belongs to, the tree says which branch, the branch holds the leaf. [Concepts](docs/concepts.md) walks
|
|
225
|
+
through one subject's life from a one-day mention to a tree of its own.
|
|
226
|
+
|
|
227
|
+
| Folder | Holds |
|
|
228
|
+
| --- | --- |
|
|
229
|
+
| `01 xltm/XLTM.md` | the root index: who the owner is, the list of trees with placement rules, the list of agents |
|
|
230
|
+
| `02 ltm/<tree>_LTM.md` | one page per tree: scope, durable patterns and rules, current state, branches |
|
|
231
|
+
| `03 mtm/<tree>/` | the tree's index (its registry of subjects) and one board per branch |
|
|
232
|
+
| `04 stm/<tree>/<branch>/` | the leaves: one sub-topic of one subject each, in full detail, at most 8 KB of content |
|
|
233
|
+
| `05 daily/` | the readable record of each day (a lane) |
|
|
234
|
+
| `06 istm/` | the raw record, append-only, one lane per agent (a lane) |
|
|
235
|
+
| `.forest/` | the compiled registry, the move log, the archive, indexes and locks |
|
|
236
|
+
|
|
237
|
+
## Agents in five lines
|
|
238
|
+
|
|
239
|
+
Several agents share one forest: shared trees for what everyone needs, a tree per agent for what is
|
|
240
|
+
its own, and an orchestrator that reads all of it. An agent that joins with `forest setup` has its tree
|
|
241
|
+
when setup answers `done`. Any other agent's tree comes by itself: when an agent writes the first line to
|
|
242
|
+
its raw lane, the next upkeep step makes its tree.
|
|
243
|
+
|
|
244
|
+
```sh
|
|
245
|
+
ls "my-forest/06 istm/post-bot" # the agent wrote its first line here
|
|
246
|
+
# 2042-05-15.jsonl
|
|
247
|
+
forest levels apply --root my-forest # one command, the same upkeep step that settles every level
|
|
248
|
+
# post-bot: none -> tree (agent; its raw lane holds a file)
|
|
249
|
+
ls my-forest/"02 ltm"
|
|
250
|
+
# post-bot_LTM.md studio_LTM.md # its tree page: role, instructions, lessons, current state, branches
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
1. An agent (an orchestrator, a bot, a scheduled stage) is a subject that is a tree from its first day.
|
|
254
|
+
A turn it writes with `forest log` or `memory_log` makes the tree, or leaves it pending for the next
|
|
255
|
+
write after another writer releases the lock. An agent is its name, in any script. The exact stored
|
|
256
|
+
id wins before the name key, across the whole forest, before group membership. Names are encoded
|
|
257
|
+
where page syntax needs it; admitted names are never refused by a second name rule.
|
|
258
|
+
`forest levels apply` makes the tree that a settings entry or an intake lane left due.
|
|
259
|
+
2. Its tree page holds its role, standing instructions, lessons, current state and branches.
|
|
260
|
+
3. `subject-first` (default) files facts in the subject's home tagged `noted by <agent>`; `agent-first`
|
|
261
|
+
files them in the agent's tree with `about:` pointers, and shares a fact once two agents hold it.
|
|
262
|
+
4. An orchestrator reads the whole forest; other agents read shared trees and their own.
|
|
263
|
+
5. Each agent appends to its own raw lane, and one filing run at a time writes the forest under a lock.
|
|
264
|
+
|
|
265
|
+
The lane commit fixes `stored` and the turn id; ids, caller-key and source records, the tree, the index and connection bookkeeping are derived, with `pending` and a reason when unfinished.
|
|
266
|
+
|
|
267
|
+
If a crash loses the answer, the caller cannot know whether the turn was stored; repeating the call with its key is safe.
|
|
268
|
+
|
|
269
|
+
Details: [Agents](docs/multi-agent.md).
|
|
270
|
+
|
|
271
|
+
## All the commands
|
|
272
|
+
|
|
273
|
+
The commands use `--root` when you pass it, and otherwise the nearest folder at or above the current one
|
|
274
|
+
that holds `forest.toml`. `forest init` and `forest setup` create a forest; `forest guide` needs none. The
|
|
275
|
+
block below creates a forest and enters it, so each following line finds that file.
|
|
276
|
+
|
|
277
|
+
```sh
|
|
278
|
+
# Milestone 1: skeleton and structure tools
|
|
279
|
+
forest init my-forest # settings, layers, root index
|
|
280
|
+
cd my-forest # this folder is the forest the commands below use
|
|
281
|
+
forest move new-agent studio-hub --name "Studio Hub" --role "orchestrator" # or let its lane make it
|
|
282
|
+
forest registry build # compile every ## Subjects section
|
|
283
|
+
forest levels check # which subjects and agents are due a new level
|
|
284
|
+
forest levels apply # carry them out through the move tool, logged
|
|
285
|
+
forest check --sync # bring derived lists up to the pages, then every check
|
|
286
|
+
forest lint # every rule with a shape, by code
|
|
287
|
+
forest repeats check # fact lines two leaves of one subject share
|
|
288
|
+
forest record kinds # the update records' lines by kind
|
|
289
|
+
forest numbers check --all # account, card, identity and phone numbers in full
|
|
290
|
+
|
|
291
|
+
# Milestone 2: connecting and finding
|
|
292
|
+
forest setup --root . --as "Kiln Bot" --main yes --conversations all --earlier no --keeper nobody
|
|
293
|
+
# the owner's answers: the agent, its tree, its record file
|
|
294
|
+
forest intake --from jsonl --as kiln-bot --transcript transcripts/kiln-bot.jsonl --once
|
|
295
|
+
# records an exporter appended, into the agent's raw lane
|
|
296
|
+
forest intake status # lines an adapter did not understand
|
|
297
|
+
forest log --as kiln-bot # the turn is read from stdin
|
|
298
|
+
forest index build # .forest/index.sqlite, rebuildable
|
|
299
|
+
forest search "cone 5" --as kiln-bot # aliases first, then words, inside the reader's scope
|
|
300
|
+
forest timeline query "yesterday evening" --as kiln-bot
|
|
301
|
+
forest navigate --as kiln-bot # one level down from the root index
|
|
302
|
+
forest mcp --as kiln-bot # search, read, timeline, navigate, memory_log
|
|
303
|
+
forest agents # groups, lanes, and when each agent was last seen
|
|
304
|
+
forest guide # the setup guide; `routine`, `use` and `contract` are the other parts
|
|
305
|
+
forest setup # with no answers: the questions an agent asks its owner (exit 1)
|
|
306
|
+
forest doctor --as kiln-bot # proves a turn arrives and the MCP server was called (exit 1 until both)
|
|
307
|
+
|
|
308
|
+
# Milestone 3: growing. Your own agent carries out the daily record, the filing run and the upkeep run,
|
|
309
|
+
# following `forest guide routine`; the commands above judge what it wrote.
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
To see what a forest looks like before any code runs, read the invented
|
|
313
|
+
[synthetic forest](examples/synthetic-forest/README.md): an owner, three shared trees, an orchestrator and
|
|
314
|
+
two bots, two days of daily pages and a raw lane, about forty small files.
|
|
315
|
+
|
|
316
|
+
## Status
|
|
317
|
+
|
|
318
|
+
Agent Memory Forest is beta software. The version in this tree is 1.0.0b1, the first public release of
|
|
319
|
+
version 1.
|
|
320
|
+
|
|
321
|
+
- **Written:** the contract, the design, the concepts and agents guides, and an invented synthetic forest
|
|
322
|
+
that follows the contract.
|
|
323
|
+
- **Milestone 1, skeleton:** the `forest` structure commands (registry, move, levels, collections, record
|
|
324
|
+
with its history files, archive, `check`, `lint`, number starring, `recover`), agents' trees made from
|
|
325
|
+
their lanes or settings, and an undo journal for every commit, with tests on made-up forests and the
|
|
326
|
+
synthetic forest passing every check.
|
|
327
|
+
- **Milestone 2, connecting and finding:** `forest intake` reads records in the lane's shape (the `jsonl`
|
|
328
|
+
adapter, or an adapter someone plugs in through the entry point group `memory_forest.adapters`) into that
|
|
329
|
+
agent's raw lane, and `forest log` and `memory_log` write an agent's own turn. `forest index` builds the
|
|
330
|
+
search index (`.forest/index.sqlite` until `forest index reset` points at a new file). `forest search`,
|
|
331
|
+
`forest read`, `forest timeline` and `forest navigate` answer from it, inside `agents.readable_trees`,
|
|
332
|
+
and `forest mcp` serves search, read, timeline, navigate and `memory_log`. The owner's agent connects
|
|
333
|
+
itself with `forest guide`, `forest setup` and `forest doctor`
|
|
334
|
+
([design, section 15](docs/v1-design.md#15-connecting-agents)).
|
|
335
|
+
- **Milestone 3, growing:** the daily record, the filing run and the nightly upkeep are carried out by the
|
|
336
|
+
owner's own agent, following the contract (section 10) and `forest guide routine`.
|
|
337
|
+
- **Not part of this release:** readers of particular agent programs' own transcripts (whoever knows a
|
|
338
|
+
program writes its reader, [adapters](docs/adapters.md)), and an engine that runs the daily, filing and
|
|
339
|
+
upkeep stages.
|
|
340
|
+
|
|
341
|
+
The 0.3 code (`memory-forest`) stays in this tree beside version 1. It is suitable for evaluation and
|
|
342
|
+
adaptation, not for unattended high-stakes decisions.
|
|
343
|
+
|
|
344
|
+
## Contributing
|
|
345
|
+
|
|
346
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md). Keep fixtures invented, keep real forests outside Git, and run the
|
|
347
|
+
full local check before opening a pull request.
|
|
348
|
+
|
|
349
|
+
```sh
|
|
350
|
+
make check
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Security issues follow [SECURITY.md](SECURITY.md). Community participation follows
|
|
354
|
+
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
|
|
355
|
+
|
|
356
|
+
## License
|
|
357
|
+
|
|
358
|
+
Agent Memory Forest is released under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
agent_memory_forest-1.0.0b1.dist-info/licenses/LICENSE,sha256=u9QA1hnaRiYSW6_6qPQP_902ZuI41cUFtjjFIegfJCM,1071
|
|
2
|
+
memory_forest/__init__.py,sha256=3jMnJxC3MpC84wFApcELpAkhTM4KQsmTS1qaPN-8h7Q,1711
|
|
3
|
+
memory_forest/__main__.py,sha256=D31U8_ux95qF64EQ8ReT25nabzxh7ped5avpobXz_bM,49
|
|
4
|
+
memory_forest/agents.py,sha256=5LjJudVIT0p4qUxrio7HIchb8MPlFrlm8GQe-lSUhog,20651
|
|
5
|
+
memory_forest/archive.py,sha256=oLvc_nglLFmf71HeZwHg3fQ5EBFYI6_OGEf5cMH4Bt4,25826
|
|
6
|
+
memory_forest/audit.py,sha256=czKMi5ka3NMdABy9snlXEumOPS1myZlXM47AFqMqNpE,13199
|
|
7
|
+
memory_forest/checks.py,sha256=xLQsGP80kAG7QoXMS08Rq0uiG3yAfazWB-dBgTq5GNk,3911
|
|
8
|
+
memory_forest/cli.py,sha256=s23inWdGzP_7TkHGZG8KpH3JmECTQsHy0PLvvw99sa4,34053
|
|
9
|
+
memory_forest/cli_find.py,sha256=sU5mYHbALDQEYIJJIlkFU5YmQPV7Yd26EscfuyPhKYI,21856
|
|
10
|
+
memory_forest/cli_intake.py,sha256=LWha4uoH16ohhwZr-s_mVYqfL9RAFVVewAYme1bVh-8,6646
|
|
11
|
+
memory_forest/cli_setup.py,sha256=IjDn-O31gHUe9_knTS3PGqS4re7yTv-ju7yeUmhVi0s,7665
|
|
12
|
+
memory_forest/cli_upkeep.py,sha256=2up1wFnq10fe7pOzMWxRRClg1VVit_PSCU06dRxYL3A,15438
|
|
13
|
+
memory_forest/collections.py,sha256=pSZEm_vMBsMD3xpiGp8WVvcJMiKHb0Mr9xheJVmxneg,44417
|
|
14
|
+
memory_forest/config.py,sha256=o1b_JqP7GB7B8CGlpE_GBiYm9k7i3wLfogbMHjmF2CE,45712
|
|
15
|
+
memory_forest/core.py,sha256=kyWLNwm91gE3Kl_UN_LD4X7ak0MZZ4GAfw4g9D-edOk,38318
|
|
16
|
+
memory_forest/credential_ledger.py,sha256=t9QNlykBfSDzQTsxWWspeZWddIMtgOpkirvMsNtMTUw,13924
|
|
17
|
+
memory_forest/credentials.py,sha256=VoHMljzWXTq_xoYYuGQiSj4HbcklclkXmUkxpomISvE,45239
|
|
18
|
+
memory_forest/derived.py,sha256=yEfU2YmDDjDZn2s-MKXyBKVP-xQjdef9yqQG1r8FMDM,52391
|
|
19
|
+
memory_forest/doctor.py,sha256=lQJdyACq9TEJlt-H8B4uTa8p-rzq4Ve-_4Fdjw90m8k,14804
|
|
20
|
+
memory_forest/embeddings.py,sha256=nlLanRtch4j9YZ8OExG_HQypnZDk326hFY7ZGvyQZJo,1195
|
|
21
|
+
memory_forest/errors.py,sha256=_s89wCKHsqeV2nElcUVFqLA__V6CFktg4AyfQ6LPFMs,23505
|
|
22
|
+
memory_forest/forest.py,sha256=M8K8CnuF-giTYGmAMFRNvHWknXxNqou7rpJWE9209I4,237
|
|
23
|
+
memory_forest/groups.py,sha256=vlhm5vzHPL8RKmFlGHYohfzoiBMYDdtt_Ieq8G4JIhc,51837
|
|
24
|
+
memory_forest/index.py,sha256=luITQPUuC9hbfGF9jS7DMzzRHtQKtBMwIKaq8X_SL6I,16659
|
|
25
|
+
memory_forest/intake.py,sha256=QCyuxoRO5ucLwJ23YbCl01no0En8p6-3ctSt8l91j7U,92854
|
|
26
|
+
memory_forest/journal.py,sha256=3XfPrejyxzBpBiLVE6GFQ0TCQE7pcP-zziCxw7GHKbg,7818
|
|
27
|
+
memory_forest/layout.py,sha256=iIivewj65AUflljSEx15MQimPF2xfhq9xel7n_jhryQ,23522
|
|
28
|
+
memory_forest/leaving.py,sha256=jFKuX7b5EEy5r-Xl9vilrRLo5_G5tnJvZT7_Z_GNH_s,4436
|
|
29
|
+
memory_forest/levels.py,sha256=Hmr5vyfhkPl5dMHVpGLddxQKVkLrA9zB3mMCFfT5g0U,21274
|
|
30
|
+
memory_forest/lint.py,sha256=2n3rBaaAv-EJ4W6MVRgsacG5Img4NTduxnv6mCH6Tnk,47647
|
|
31
|
+
memory_forest/locking.py,sha256=19BDQrcK0P10-4X7L6qrRH_63Qaairuyqz6wJdmB3HU,13364
|
|
32
|
+
memory_forest/maps.py,sha256=PS6rQNNRvcxthGCJhpq7j9TSay8jvhIjp_JjJ0FHBd4,18703
|
|
33
|
+
memory_forest/mcp.py,sha256=ds73PbCvscp7P64Up4jIU1YM1gelFGVhObzPD0PSoqU,58668
|
|
34
|
+
memory_forest/model.py,sha256=_NsECszTQrkpKAhmosnUc5ki4-Apgopo-4THs7y7G_U,47870
|
|
35
|
+
memory_forest/move.py,sha256=DjD6HxgD7BsJU002P2adqkjyvo-VJ9Uc7vUdCKMxR6I,81966
|
|
36
|
+
memory_forest/movelog.py,sha256=jL9qoIyteURn1G_Wc68mNhoQNll9xQpqA63smNcEJdE,11902
|
|
37
|
+
memory_forest/names.py,sha256=YdK62rC9Cp2k6CQ82ixvTwGCIv6ghlNPp83GAzCoUmw,13434
|
|
38
|
+
memory_forest/numbers.py,sha256=MG_cZB0aMgBWz3CHHjPaseld7xWRaZcyArdjwSbslCw,16888
|
|
39
|
+
memory_forest/plan.py,sha256=Nsa75a5tOVMHDJZBjXhtZZCr05Hq3IfITKysyGNU0po,58426
|
|
40
|
+
memory_forest/record.py,sha256=5_NaaCKxIW5rlpV7_xZjRgOl6ZNwxOhXQ6Bnp3WY3U4,26109
|
|
41
|
+
memory_forest/registry.py,sha256=cgvoM5PDk5_Jj9G61081mBK2lEy2MyOEztOSgafrvRA,36276
|
|
42
|
+
memory_forest/repeats.py,sha256=x8S7z0ZwnUtfzbhS5lS2K3lPkM_-faYTYvqCG4RaJZU,26108
|
|
43
|
+
memory_forest/retrieval.py,sha256=4r-diFsKfoIvPAqV8Oh8D21Z3mFT7FsDVHyUPlXP5jk,29383
|
|
44
|
+
memory_forest/safety.py,sha256=x7PFxqoFZF9BEh-LmDhz5BX3l4OPuQua2mc1gWKziqw,17145
|
|
45
|
+
memory_forest/scope.py,sha256=T8NPTY-d2iOSZiArNLRFXQQzozkmTkssKQ0fSuwARcM,2703
|
|
46
|
+
memory_forest/search.py,sha256=mVditHonruNd_PnEH5GFABmlmEMDeKnbOo9xJBrTt7A,126997
|
|
47
|
+
memory_forest/setup_agent.py,sha256=0i1TWlF3tnA70iUOGvIMWsUiLF6bGEZ46M34lZGtwjo,28686
|
|
48
|
+
memory_forest/sources.py,sha256=DWDE106298S8OTanXdIfG2L64bCfeotT9z2TggYxYDk,11393
|
|
49
|
+
memory_forest/stage.py,sha256=ghH3uygkokjda_PJuxf2ExNIZtzouhQ3hg2CXqeeg5U,3970
|
|
50
|
+
memory_forest/system.py,sha256=h2g9spz6PV2CxY3KOU7aNbXwGHFFS9mVZpWQBhrd1xQ,66104
|
|
51
|
+
memory_forest/timeline.py,sha256=KrRySpjOSZtTgh4SnslftM8NbUiYJ02u-dbz7-ecHGY,22228
|
|
52
|
+
memory_forest/tool_commands.py,sha256=NSBlLuWaHz23WpjMXXXv4qbmGrFmgPp3xPEluVSCuA8,13679
|
|
53
|
+
memory_forest/turn_keys.py,sha256=WTly2G0zsEDWUdQ4tbbgz23QghXKbcgRdg-9R-vVcvw,4272
|
|
54
|
+
memory_forest/validate.py,sha256=QCYEGkpG0Y95Dto_shgy1Tq6S64LVVN8CIm0_rMPLQU,10724
|
|
55
|
+
memory_forest/view.py,sha256=HA6sICohMYKA4TH2Ir8h8VhNdKufIQ12CgICgUtBRfA,8208
|
|
56
|
+
memory_forest/writer.py,sha256=jtXClosW3QrCDMlMM1DtXTmJiLYIsqZ-fgVHbFPyAaU,101315
|
|
57
|
+
memory_forest/adapters/__init__.py,sha256=oV0eq99ciIgRKqpOLaDwKh-lEYiHNxGW7wdfFGknZfU,5283
|
|
58
|
+
memory_forest/adapters/common.py,sha256=f6qm0Z1QpI1uJrNqHw1aog5cw40RLtG-_g6Z8zxZWiQ,11258
|
|
59
|
+
memory_forest/adapters/jsonl.py,sha256=DwUH3boBs4Dqti-Mpji5NdDy6AllTAp9ZbTRUwthATQ,8375
|
|
60
|
+
memory_forest/guide/contract.md,sha256=DcY5aqyBYFSTs8puFfgdjz0M5fp4Zr947wWuVEwYITk,106975
|
|
61
|
+
memory_forest/guide/routine.md,sha256=p4rGyyK8QetRNlZRu268upvbbPtn6jvP5HObmiZGlcQ,10827
|
|
62
|
+
memory_forest/guide/setup.md,sha256=NdN6saitw75PYgnOKhbJaiqB-Y6dJtyuiaBYa-noxr4,8614
|
|
63
|
+
memory_forest/guide/use.md,sha256=BDJR2RrcQwrfWYMDaWI_utc_RQPyVC7M3CnbovDRiok,3168
|
|
64
|
+
memory_forest/letters/cyrillic.json,sha256=tHmqZuV2vnyf1wIQBPrLrg58K2RsWH03ObX6WK-X3gE,781
|
|
65
|
+
memory_forest/letters/greek.json,sha256=wQUl-LCcTilYWzUm5662iMWvz4aj7ggANETy1Wv5mZk,466
|
|
66
|
+
memory_forest/letters/hangul.json,sha256=o37rNS9aZBsbvttFPz_uxhXgjho-0hGPESn9zvRR73M,1229
|
|
67
|
+
memory_forest/letters/kana.json,sha256=ZS_BjR-S8M-r9i6G7_sbJFkOTdekvJfp4blR5i9D9k4,4689
|
|
68
|
+
memory_forest/letters/latin.json,sha256=n3HDkr0SPfuK-_wGF3mt17ZbHUUP1KBnr0YyG5YCp0A,673
|
|
69
|
+
memory_forest/phrases/ko.json,sha256=e5jRZMaqCB_s1zY9OeKcJ9qW-tIPWM15-R8w4ePuJO4,1123
|
|
70
|
+
agent_memory_forest-1.0.0b1.dist-info/METADATA,sha256=gsRhNgd3P7s27j9T23WtgFU2wzN4AjOml06BQMIFy9k,21390
|
|
71
|
+
agent_memory_forest-1.0.0b1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
72
|
+
agent_memory_forest-1.0.0b1.dist-info/entry_points.txt,sha256=TXZykQoLqx0kfWnEM8Cq8fO8erKM9p6BUxBJ5Stv7mE,167
|
|
73
|
+
agent_memory_forest-1.0.0b1.dist-info/top_level.txt,sha256=1yi1MZwuuZaIUKilgV_OGaIbJ2DTdtco6wHGbzRnv2Q,14
|
|
74
|
+
agent_memory_forest-1.0.0b1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hyungchul Choi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
memory_forest
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
from .core import (
|
|
2
|
+
audit_forest,
|
|
3
|
+
doctor_forest,
|
|
4
|
+
initialize_forest,
|
|
5
|
+
inspect_forest,
|
|
6
|
+
load_forest_identity,
|
|
7
|
+
validate_forest,
|
|
8
|
+
)
|
|
9
|
+
from .errors import MemoryForestError
|
|
10
|
+
from .index import index_forest, route_index, search_index
|
|
11
|
+
from .model import Layer, Route, immediate_parent_path, parse_layer, parse_relative_route
|
|
12
|
+
from .retrieval import (
|
|
13
|
+
QueryPlan,
|
|
14
|
+
retrieve_index,
|
|
15
|
+
structured_context_index,
|
|
16
|
+
validate_query_plan,
|
|
17
|
+
)
|
|
18
|
+
from .safety import DEFAULT_LIMITS, ForestLimits
|
|
19
|
+
from .writer import (
|
|
20
|
+
DAILY_PLAN_SCHEMA,
|
|
21
|
+
PROMOTION_PLAN_SCHEMA,
|
|
22
|
+
STRUCTURED_SWEEP_PLAN_SCHEMA,
|
|
23
|
+
WRITE_RECEIPT_SCHEMA,
|
|
24
|
+
DailyPlan,
|
|
25
|
+
PromotionPlan,
|
|
26
|
+
StructuredSweepPlan,
|
|
27
|
+
apply_daily,
|
|
28
|
+
apply_structured_sweep,
|
|
29
|
+
promote,
|
|
30
|
+
validate_daily_plan,
|
|
31
|
+
validate_promotion_plan,
|
|
32
|
+
validate_structured_sweep_plan,
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
__version__ = "1.0.0b1"
|
|
37
|
+
|
|
38
|
+
__all__ = [
|
|
39
|
+
"DEFAULT_LIMITS",
|
|
40
|
+
"DAILY_PLAN_SCHEMA",
|
|
41
|
+
"ForestLimits",
|
|
42
|
+
"Layer",
|
|
43
|
+
"MemoryForestError",
|
|
44
|
+
"PROMOTION_PLAN_SCHEMA",
|
|
45
|
+
"PromotionPlan",
|
|
46
|
+
"STRUCTURED_SWEEP_PLAN_SCHEMA",
|
|
47
|
+
"StructuredSweepPlan",
|
|
48
|
+
"QueryPlan",
|
|
49
|
+
"Route",
|
|
50
|
+
"WRITE_RECEIPT_SCHEMA",
|
|
51
|
+
"DailyPlan",
|
|
52
|
+
"__version__",
|
|
53
|
+
"audit_forest",
|
|
54
|
+
"apply_daily",
|
|
55
|
+
"apply_structured_sweep",
|
|
56
|
+
"doctor_forest",
|
|
57
|
+
"index_forest",
|
|
58
|
+
"immediate_parent_path",
|
|
59
|
+
"initialize_forest",
|
|
60
|
+
"inspect_forest",
|
|
61
|
+
"load_forest_identity",
|
|
62
|
+
"parse_layer",
|
|
63
|
+
"parse_relative_route",
|
|
64
|
+
"promote",
|
|
65
|
+
"route_index",
|
|
66
|
+
"retrieve_index",
|
|
67
|
+
"search_index",
|
|
68
|
+
"structured_context_index",
|
|
69
|
+
"validate_query_plan",
|
|
70
|
+
"validate_forest",
|
|
71
|
+
"validate_daily_plan",
|
|
72
|
+
"validate_promotion_plan",
|
|
73
|
+
"validate_structured_sweep_plan",
|
|
74
|
+
]
|