SHUKUMEI
- define 'real'. -
[Shukumei_beta source tgz] - wip/PoC : Oct 14, 2026
[Shukumei_beta plaintxt src rollup] : Oct 14, 2026
[prepopulated example save state] : Oct 14, 2026
[rollup of system prompts in save state] : Oct 14, 2026
-use at your own risk-
[Shukumei] is a harness written for the [plan9] operating system. For quickest understanding - think sillytavern but running in acme.
Only supports llama.cpp without authentication (local running llama.cpp server on the same network with http api listening locally.)
This may change in the future. But for now local llama.cpp is fine for the use case we have, so we'd need compelled to care.
The api in the code is very close to OAI endpoints, but embedding is llama.cpp specific because the OAI endpoint sucks to parse and i didn't want to deal with it.
To install download source, modify shukumei.c to point to your llama.cpp ip. install [libhnsw]. `mk` and `mk install`
To run it, navigate to a "world" (example minimal world directory included, additional prepopulated world save state included above) and run acme then run win then run START in win. (don't run START out of win, it needs the stdin from win's cmdline) alternatively run shukumei from inside the world directory. (redirect 2 to remove 'debug' clutter).
The START flow is the intended use method and it sets up 2 additional windows, one for output messages and one for debug messages.
the system prompts the user with >>>
end a prompt with `ctrl+c return` on a line by itself.
close the harness (saving data) with `ctrl+\`
close the harness (without saving) with `del`
head.id contains the id of the current "save" directory in Memories. (can be changed to point to specific memory instance, ie to branch memory state or go back)
Memories contains every save the system has seen. Sorting with `ls -lt` will tell you when they were modified.
note : you may think that this is wasteful. if you are not using a deduplicating FS (you probably are and don't need to worry) then store your world file on /tmp or something and clear out old ones. but i'm pretty sure cwfs, fossil/venti, hjfs, and gefs all do block deduplication so the save files won't be using nearly as much storage as you likely think.
in a Memory file the following [slov] files exist([optional]) - 役顔.slov [連中.slov] [命一.slov] [命三.slov] [vwrap.slov] [残滓.slov] [欠片.slov] [ring.id]
Explaination of files :
- 役顔.slov - contains the definition of personas in the system. Minimally includes a distil persona ( 血 : -2 ) and another persona ( 血 : 0 or 1 )
血 values determine role/backend. 1 is human stdin. 0 is LLM call. these types both have HNSW memory storage attached. -1 is an LLM that does not have memory. (considered "adhoc" or "temporary"). -2 is a distil.
To disable a persona without deleting their memories set their value to 2<=value<=127. This will exclude them from the list of avalible personas, will not populate their graph, but importantly will not remove their memories from the database. a fully removed persona will have their memories removed from the next save.
名s is used for aliases for the persona. because summarization uses an LLM, this is to prevent problems where the summarizer sees a nickname and decides it's the "correct name" for the entry in it's output. It can also be used instead of the full name for commands that need a persona name (/enter name, /leave name, @name)
Each persona must have a Name.md in the root of the world directory. The name must match the name exactly (capitalization must match) and not one of the aliases.
Names and Aliases must be unique.
This is the only mandatory memory file and the only one a user is expected to edit.
- 連中.slov - contains the seen cohorts (lists of personas).
- 命一.slov - contains the raw interaction data.
- 命三.slov - contains nodes that link groups of interactions (3 interactions in a sequence) to the cohort involved and the summary objects.
- vwrap.slov - contains deduplicated vector embeddings. These ids are linked to by 残滓 and 欠片
- 残滓.slov - contains summary data linked to 命三 groups and specific 役顔 it belongs to. contains list of 欠片 attached
- 欠片.slov - contains fact data linked to the 残滓s.
currently there are no commands supported. to change "present persona" list, save with [ctrl+\] modify the memory pointed to at head.id to change persona visibility (set 血 to 0 to include, and like 10 to exclude). is this annoying? yes. it will change. soon probably.
Notes from actual use:
Don't start the memory graphs for personas with multi agent setup.
ideally fill the persona graph untill well after recall is working to give each persona a decent 'floor' of memories in a one on one setting, covering a variety of subject matter. clear ring.id between changing personas to prevent giving subsequent personas the linear history of interactions with the previous. Once the personas have been 'raised' in a one on one setting their graphs can probably tolerate interaction with other personas.
the fail state of an early fixation on poetic vagueary due to llm-lmm-lmm type interactions is recoverable by merging in a good floor of one on one interactions. (cat merge save files. the uids should not colide with 126 bits of entropy) changing the save state folder is fine, head.id doesn't care if it's in the shape of the uid only that the name is unique.
i hope that makes sense to someone other than me... :shrugs:
SRC UPDATES:
Oct 14, 2026 - vector storage change. Both old and new vector formats supported on load. Saving only in new format. (disk space should be much lower, especially with many active personas). You should not lose any valid memories, however, it was possible for unretrivable memories to be entered into the database before now. The base interactions will remain. You may get some complaints about "using old vector loading". This is expected. Change to lost embedding server logic. now waits for user intervention with save and quit/retry. many hydration logic changes to support both modes. empty nodes no longer being saved.
Oct 10, 2026 - budget bump (8k to 12k), recall memories no longer capped to 3 triplets, hydration bug for lists with leading whitespace fixed (important memory corruption bug that deleted lines in output that started with tabs in interactions), fixed empty ring.id crash, distil fact extraction logic updated.
Oct 8, 2026 - cleanup ad hoc persona handling, void 役/残滓 hydration fix
Sept 30, 2026 - initial release
tags
clanker code plan9 red safe shukumei_loading technology