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.
Files changed (74) hide show
  1. agent_memory_forest-1.0.0b1.dist-info/METADATA +358 -0
  2. agent_memory_forest-1.0.0b1.dist-info/RECORD +74 -0
  3. agent_memory_forest-1.0.0b1.dist-info/WHEEL +5 -0
  4. agent_memory_forest-1.0.0b1.dist-info/entry_points.txt +6 -0
  5. agent_memory_forest-1.0.0b1.dist-info/licenses/LICENSE +21 -0
  6. agent_memory_forest-1.0.0b1.dist-info/top_level.txt +1 -0
  7. memory_forest/__init__.py +74 -0
  8. memory_forest/__main__.py +4 -0
  9. memory_forest/adapters/__init__.py +143 -0
  10. memory_forest/adapters/common.py +347 -0
  11. memory_forest/adapters/jsonl.py +216 -0
  12. memory_forest/agents.py +449 -0
  13. memory_forest/archive.py +639 -0
  14. memory_forest/audit.py +287 -0
  15. memory_forest/checks.py +91 -0
  16. memory_forest/cli.py +868 -0
  17. memory_forest/cli_find.py +585 -0
  18. memory_forest/cli_intake.py +172 -0
  19. memory_forest/cli_setup.py +148 -0
  20. memory_forest/cli_upkeep.py +287 -0
  21. memory_forest/collections.py +1004 -0
  22. memory_forest/config.py +1028 -0
  23. memory_forest/core.py +1085 -0
  24. memory_forest/credential_ledger.py +334 -0
  25. memory_forest/credentials.py +998 -0
  26. memory_forest/derived.py +1063 -0
  27. memory_forest/doctor.py +273 -0
  28. memory_forest/embeddings.py +40 -0
  29. memory_forest/errors.py +549 -0
  30. memory_forest/forest.py +8 -0
  31. memory_forest/groups.py +1202 -0
  32. memory_forest/guide/contract.md +1305 -0
  33. memory_forest/guide/routine.md +292 -0
  34. memory_forest/guide/setup.md +164 -0
  35. memory_forest/guide/use.md +52 -0
  36. memory_forest/index.py +502 -0
  37. memory_forest/intake.py +2215 -0
  38. memory_forest/journal.py +181 -0
  39. memory_forest/layout.py +593 -0
  40. memory_forest/leaving.py +115 -0
  41. memory_forest/letters/cyrillic.json +55 -0
  42. memory_forest/letters/greek.json +32 -0
  43. memory_forest/letters/hangul.json +73 -0
  44. memory_forest/letters/kana.json +283 -0
  45. memory_forest/letters/latin.json +48 -0
  46. memory_forest/levels.py +483 -0
  47. memory_forest/lint.py +1028 -0
  48. memory_forest/locking.py +359 -0
  49. memory_forest/maps.py +458 -0
  50. memory_forest/mcp.py +1413 -0
  51. memory_forest/model.py +1299 -0
  52. memory_forest/move.py +1554 -0
  53. memory_forest/movelog.py +308 -0
  54. memory_forest/names.py +324 -0
  55. memory_forest/numbers.py +410 -0
  56. memory_forest/phrases/ko.json +42 -0
  57. memory_forest/plan.py +1308 -0
  58. memory_forest/record.py +619 -0
  59. memory_forest/registry.py +880 -0
  60. memory_forest/repeats.py +531 -0
  61. memory_forest/retrieval.py +839 -0
  62. memory_forest/safety.py +480 -0
  63. memory_forest/scope.py +81 -0
  64. memory_forest/search.py +3153 -0
  65. memory_forest/setup_agent.py +521 -0
  66. memory_forest/sources.py +250 -0
  67. memory_forest/stage.py +108 -0
  68. memory_forest/system.py +1712 -0
  69. memory_forest/timeline.py +556 -0
  70. memory_forest/tool_commands.py +234 -0
  71. memory_forest/turn_keys.py +101 -0
  72. memory_forest/validate.py +264 -0
  73. memory_forest/view.py +194 -0
  74. 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
+ [![CI](https://github.com/hyungchulc/agent-memory-forest/actions/workflows/ci.yml/badge.svg)](https://github.com/hyungchulc/agent-memory-forest/actions/workflows/ci.yml)
34
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB.svg)](https://www.python.org/)
35
+ [![License: MIT](https://img.shields.io/badge/license-MIT-2EA44F.svg)](LICENSE)
36
+ [![Local-first](https://img.shields.io/badge/runtime-local--first%20%7C%20no%20network-555555.svg)](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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,6 @@
1
+ [console_scripts]
2
+ forest = memory_forest.cli:forest_main
3
+ memory-forest = memory_forest.cli:main
4
+
5
+ [memory_forest.adapters]
6
+ jsonl = memory_forest.adapters.jsonl:adapter
@@ -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
+ ]
@@ -0,0 +1,4 @@
1
+ from .cli import main
2
+
3
+
4
+ raise SystemExit(main())