my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	<p align="center">
#2	<img src="assets/clawd-brain-memory.svg" alt="Animated Clawd Brain memory system" width="100%" />
#3	</p>
#4
#5	<h1 align="center">Clawd Memory</h1>
#6
#7	<p align="center">
#8	<strong>Clawd Brain update: local agent memory, markdown vaults, Solana research, OODA ingestion, and fast recall.</strong>
#9	</p>
#10
#11	<p align="center">
#12	<a href="https://clawd.x402.wtf/site/"><img alt="Clawd Site" src="https://img.shields.io/badge/site-clawd.x402.wtf-9945FF?style=for-the-badge"></a>
#13	<img alt="Memory Bank" src="https://img.shields.io/badge/default_bank-clawd-14F195?style=for-the-badge">
#14	<img alt="Local First" src="https://img.shields.io/badge/storage-local_first-090612?style=for-the-badge">
#15	<img alt="Agent Ready" src="https://img.shields.io/badge/agents-ready-9945FF?style=for-the-badge">
#16	</p>
#17
#18	```text
#19	CLAWD BRAIN MEMORY LOOP
#20
#21	user intent OODA ticks Solana research agent decisions
#22	\| \| \| \|
#23	v v v v
#24	+-----------------------------------------------------------------------+
#25	\| clawd-brain \|
#26	\| remember -> vault note -> SQLite bank -> recall -> action \|
#27	+-----------------------------------------------------------------------+
#28	\| \| \| \|
#29	v v v v
#30	preferences risk notes protocol docs reusable context
#31	```
#32
#33	Local-first memory for Clawd agents.
#34
#35	Clawd Memory is the persistent brain layer for Solana Clawd. It gives agents a durable memory bank, a markdown research vault, fast local recall, and a simple CLI for saving decisions, user preferences, wallet notes, protocol research, trading context, and agent operating state.
#36
#37	The storage engine is the existing `mnemosyne` Python package. The Clawd interface is `clawd-brain`, backed by the default `clawd` bank and the `MemeBRain/vault` markdown vault. Keep the engine names stable unless you are ready to migrate imports, plugin paths, and stored data.
#38
#39	## What It Does
#40
#41	- Stores agent memory locally in SQLite, with no required cloud database.
#42	- Keeps a Clawd markdown vault with folders for research, signals, trades, agents, protocols, wallets, and perps.
#43	- Recalls context with hybrid memory search and matching vault notes.
#44	- Archives URLs and research prompts into durable notes.
#45	- Imports OODA journal ticks into memory.
#46	- Supports Hermes/MCP integrations through the existing Mnemosyne-compatible tools.
#47
#48	## Quick Start
#49
#50	From this directory:
#51
#52	```bash
#53	cd /Users/8bit/bots/Cladwbot-solana/solana-clawd/MemeBRain
#54	python3 -m mnemosyne.clawd_brain init
#55	python3 -m mnemosyne.clawd_brain remember "Jupiter Perps Risk" "Track [[Jupiter]] liquidity, funding, route quality, and oracle failure modes." --kind perp --tag solana --tag risk
#56	python3 -m mnemosyne.clawd_brain recall "Jupiter perp risk"
#57	python3 -m mnemosyne.clawd_brain status
#58	```
#59
#60	If installed as a package, use the console script:
#61
#62	```bash
#63	clawd-brain init
#64	clawd-brain remember "User Preference" "The user wants concise, direct engineering updates." --kind agent --tag preference
#65	clawd-brain research "https://docs.jup.ag/"
#66	clawd-brain recall "user communication preferences"
#67	```
#68
#69	From the repo root, the helper scripts may also be available:
#70
#71	```bash
#72	npm run brain:init
#73	npm run brain:status
#74	npm run brain:ingest-ooda
#75	```
#76
#77	## Agent Memory Contract
#78
#79	Agents should use Clawd Memory deliberately:
#80
#81	- Recall before planning when the task involves a returning user, existing protocol research, wallet history, trading notes, or previous architecture decisions.
#82	- Remember durable facts, preferences, decisions, risk findings, protocol notes, wallet labels, deployment details, and postmortems.
#83	- Do not remember transient command output, secrets, raw API keys, private keys, or noisy stack traces unless the user explicitly asks for an incident record.
#84	- Prefer short, factual memories with clear titles, tags, source, and kind.
#85	- Use `research` for URLs and investigation topics that should become vault notes.
#86	- Use `ingest-ooda` to convert OODA ticks into durable agent context.
#87
#88	Useful kinds:
#89
#90	\| Kind \| Use \|
#91	\|---\|---\|
#92	\| `agent` \| Operating rules, user preferences, workflow decisions \|
#93	\| `research` \| URLs, protocol notes, market structure, docs \|
#94	\| `signal` \| Market, social, token, or infrastructure signal \|
#95	\| `trade` \| Trade plans, entry/exit rationale, post-trade review \|
#96	\| `protocol` \| Solana protocol knowledge and integration notes \|
#97	\| `wallet` \| Public wallet labels, behavior notes, portfolio context \|
#98	\| `perp` \| Perpetual venue, oracle, liquidation, funding, or route risk \|
#99	\| `note` \| General memory \|
#100
#101	## Storage Layout
#102
#103	Clawd Memory writes to two local stores:
#104
#105	```text
#106	MemeBRain/vault/
#107	├── 00-inbox/
#108	├── 10-research/
#109	├── 20-signals/
#110	├── 30-trades/
#111	├── 40-agents/
#112	├── 50-protocols/
#113	├── 60-wallets/
#114	├── 70-perps/
#115	└── 90-indexes/clawd-brain.db
#116	```
#117
#118	The SQLite memory engine uses `MNEMOSYNE_DATA_DIR`, defaulting to the Hermes data directory when unset. Named banks live under that data directory. The Clawd default bank is `clawd`.
#119
#120	Important environment variables:
#121
#122	\| Variable \| Purpose \|
#123	\|---\|---\|
#124	\| `CLAWD_BRAIN_VAULT` \| Override the markdown vault path \|
#125	\| `MNEMOSYNE_DATA_DIR` \| Override the SQLite memory data directory \|
#126	\| `MNEMOSYNE_VEC_TYPE` \| Vector storage type: `int8`, `float32`, or `bit` \|
#127	\| `MNEMOSYNE_HOST_LLM_ENABLED` \| Let a host agent framework provide the LLM for consolidation \|
#128	\| `MNEMOSYNE_LLM_BASE_URL` \| OpenAI-compatible remote LLM base URL for consolidation \|
#129	\| `MNEMOSYNE_LLM_API_KEY` \| API key for the remote LLM endpoint \|
#130	\| `MNEMOSYNE_LLM_MODEL` \| Model identifier for consolidation \|
#131
#132	## CLI Reference
#133
#134	```bash
#135	clawd-brain --help
#136	clawd-brain init
#137	clawd-brain status
#138	clawd-brain remember TITLE CONTENT --kind research --source clawd --tag solana --importance 0.8
#139	clawd-brain recall QUERY --top-k 8
#140	clawd-brain research URL_OR_TOPIC --tag solana
#141	clawd-brain ingest-ooda --journal ../ooda/journal/ticks.jsonl --limit 100
#142	```
#143
#144	Every command accepts:
#145
#146	```bash
#147	--bank clawd
#148	--vault /path/to/vault
#149	```
#150
#151	## Python Usage
#152
#153	Use the Clawd layer for agent-facing memory:
#154
#155	```python
#156	from mnemosyne.clawd_brain import ClawdBrain
#157
#158	brain = ClawdBrain()
#159	brain.remember(
#160	"Clawd Gateway",
#161	"The public worker endpoint is https://clawd.x402.wtf.",
#162	kind="agent",
#163	tags=["deployment", "worker"],
#164	)
#165
#166	result = brain.recall("worker endpoint")
#167	print(result)
#168	```
#169
#170	Use the lower-level engine only when you need raw BEAM operations:
#171
#172	```python
#173	from mnemosyne import Mnemosyne
#174
#175	mem = Mnemosyne(bank="clawd", session_id="clawd-brain")
#176	mem.remember("Raw engine memory", importance=0.5)
#177	print(mem.recall("engine memory"))
#178	```
#179
#180	## Hermes And MCP
#181
#182	The Hermes plugin and MCP server still expose `mnemosyne_*` tool names for compatibility:
#183
#184	\| Tool \| Clawd usage \|
#185	\|---\|---\|
#186	\| `mnemosyne_remember` \| Store durable Clawd agent memory \|
#187	\| `mnemosyne_recall` \| Retrieve relevant context before a response or action \|
#188	\| `mnemosyne_sleep` \| Consolidate working memory into episodic memory \|
#189	\| `mnemosyne_stats` \| Inspect memory state \|
#190	\| `mnemosyne_scratchpad_*` \| Use temporary reasoning workspace \|
#191	\| `mnemosyne_triple_*` \| Store/query temporal knowledge graph facts \|
#192
#193	For new Clawd-native code, prefer `ClawdBrain` or `clawd-brain`. For existing Hermes/MCP clients, keep the compatibility tool names.
#194
#195	## Architecture
#196
#197	Clawd Memory has four layers:
#198
#199	\| Layer \| Responsibility \|
#200	\|---\|---\|
#201	\| Agent contract \| When to recall, remember, research, and consolidate \|
#202	\| Clawd brain layer \| `ClawdBrain`, vault notes, tags, Solana/OODA metadata \|
#203	\| Memory engine \| BEAM working memory, episodic memory, scratchpad, hybrid recall \|
#204	\| Persistence \| SQLite databases and markdown vault files \|
#205
#206	See [docs/architecture.md](docs/architecture.md) for details.
#207
#208	## Docs
#209
#210	- [Getting Started](docs/getting-started.md)
#211	- [Architecture](docs/architecture.md)
#212	- [Configuration](docs/configuration.md)
#213	- [API Reference](docs/api-reference.md)
#214	- [Hermes Integration](docs/hermes-integration.md)
#215	- [LLM Agent Installation Guide](docs/llm-installation-guide.md)
#216	- [Comparison Notes](docs/comparison.md)
#217	- [BEAM Benchmark](docs/beam-benchmark.md)
#218
#219	## Compatibility Notes
#220
#221	- Package name: `mnemosyne-memory`
#222	- Python module: `mnemosyne`
#223	- Clawd CLI: `clawd-brain`
#224	- Clawd Python class: `mnemosyne.clawd_brain.ClawdBrain`
#225	- Default Clawd bank: `clawd`
#226	- Default Clawd vault: `MemeBRain/vault`
#227
#228	This split is intentional. It lets Clawd own the agent memory workflow without breaking the existing storage engine, package metadata, import paths, Hermes adapter, or MCP clients.
#229

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public