my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Clawd Memory Architecture
#2
#3	Clawd Memory is a local-first memory system for agents. It keeps the user-facing workflow Clawd-native while reusing the existing Mnemosyne SQLite engine for persistence, BEAM tiers, search, and integrations.
#4
#5	## Layers
#6
#7	```text
#8	Clawd agents
#9	\|
#10	\| recall / remember / research / ingest-ooda
#11	v
#12	ClawdBrain
#13	\|
#14	\| writes markdown notes, metadata, links, and memory entries
#15	v
#16	Clawd vault + index
#17	\|
#18	\| note lookup, kind/source/tag filtering
#19	v
#20	Mnemosyne engine
#21	\|
#22	\| working memory, episodic memory, scratchpad, triples
#23	v
#24	SQLite files
#25	```
#26
#27	## Clawd Brain Layer
#28
#29	The Clawd layer lives in `mnemosyne.clawd_brain`.
#30
#31	Key defaults:
#32
#33	\| Setting \| Default \|
#34	\|---\|---\|
#35	\| Bank \| `clawd` \|
#36	\| Session \| `clawd-brain` \|
#37	\| Vault env var \| `CLAWD_BRAIN_VAULT` \|
#38	\| Vault path \| `MemeBRain/vault` \|
#39	\| Index database \| `vault/90-indexes/clawd-brain.db` \|
#40
#41	The vault layout is created on `init`:
#42
#43	```text
#44	00-inbox/
#45	10-research/
#46	20-signals/
#47	30-trades/
#48	40-agents/
#49	50-protocols/
#50	60-wallets/
#51	70-perps/
#52	90-indexes/
#53	```
#54
#55	Each Clawd note gets frontmatter, tags, kind, source, timestamps, an optional memory ID, and wiki link extraction. The index database tracks notes and links so recall can return both engine memories and matching vault notes.
#56
#57	## BEAM Engine
#58
#59	The underlying engine uses BEAM: Bilevel Episodic-Associative Memory.
#60
#61	```text
#62	Working memory
#63	hot session/global context, TTL-based eviction, prompt injection
#64
#65	Episodic memory
#66	long-term consolidated memory, hybrid vector/FTS/importance recall
#67
#68	Scratchpad
#69	temporary reasoning workspace, not durable knowledge
#70
#71	Triples
#72	temporal subject-predicate-object facts with valid_from/valid_until
#73	```
#74
#75	The engine is still imported as `mnemosyne`. That name is an implementation detail for Clawd docs unless you are writing Python against the lower-level API.
#76
#77	## Recall Pipeline
#78
#79	Clawd recall combines two sources:
#80
#81	1. Engine recall through `Mnemosyne.recall(query, top_k)`.
#82	2. Vault lookup through the Clawd note index.
#83
#84	The engine pipeline can use:
#85
#86	- SQLite FTS5 for lexical search.
#87	- sqlite-vec or fallback vector search for semantic search.
#88	- Importance scores for agent-weighted memories.
#89	- Recency and metadata filters in lower-level APIs.
#90
#91	The Clawd layer adds Solana-aware tags, note kinds, markdown links, and durable source metadata.
#92
#93	## Remember Pipeline
#94
#95	```text
#96	remember(title, content, kind, source, tags, importance)
#97	\|
#98	\| detect domain tags and wiki links
#99	\| write markdown note to vault folder for kind
#100	\| write memory to default clawd bank
#101	\| update vault index database
#102	v
#103	JSON result with note path, tags, memory ID, and timestamps
#104	```
#105
#106	Agents should remember durable state only. Temporary chain-of-thought, raw logs, and secrets do not belong in durable memory.
#107
#108	## Research Pipeline
#109
#110	```text
#111	research(target)
#112	\|
#113	\| if target is URL: fetch title and readable text snippet
#114	\| if target is topic: create queued research note
#115	\| tag and index the note
#116	\| store the summary as memory
#117	v
#118	reusable research artifact
#119	```
#120
#121	Use this for Solana protocol docs, x402/AP2 notes, venue risk, wallet investigations, and reusable agent research.
#122
#123	## OODA Ingestion
#124
#125	`ingest-ooda` reads an OODA journal JSONL file and converts observations into Clawd memory. This is how operational loops become durable context for later planning.
#126
#127	Default journal path:
#128
#129	```text
#130	../ooda/journal/ticks.jsonl
#131	```
#132
#133	## Persistence
#134
#135	Clawd Memory persists locally:
#136
#137	\| Store \| Purpose \|
#138	\|---\|---\|
#139	\| `MemeBRain/vault` \| Human-readable markdown research and memory notes \|
#140	\| `vault/90-indexes/clawd-brain.db` \| Note and wiki link index \|
#141	\| `MNEMOSYNE_DATA_DIR` \| Engine SQLite databases and named banks \|
#142	\| `~/.hermes/mnemosyne/data` \| Default engine data directory when unset \|
#143
#144	Back up both the vault and engine data directory if you want a complete Clawd brain backup.
#145
#146	## Compatibility Boundaries
#147
#148	Do not rename these without a migration plan:
#149
#150	\| Name \| Why it stays \|
#151	\|---\|---\|
#152	\| `mnemosyne-memory` \| Published package/distribution name \|
#153	\| `mnemosyne` \| Python import path used across code and integrations \|
#154	\| `mnemosyne_*` tools \| Hermes/MCP compatibility surface \|
#155	\| `MNEMOSYNE_*` env vars \| Engine configuration \|
#156
#157	Use these for new Clawd-facing workflows:
#158
#159	\| Name \| Purpose \|
#160	\|---\|---\|
#161	\| `clawd-brain` \| CLI \|
#162	\| `ClawdBrain` \| Python API \|
#163	\| `CLAWD_BRAIN_VAULT` \| Clawd vault override \|
#164	\| `clawd` \| Default memory bank \|
#165

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public