Skip to content

Commit 56983cb

Browse files
daveragedaverage
committed
tinyTask enforcment update (Release v0.2.1)
1 parent 3cc4d29 commit 56983cb

21 files changed

+3901
-1
lines changed

‎TINYMEM_ARCHITECTURE.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# tinyMem Architecture
2+
3+
## Executive Summary
4+
5+
tinyMem is a multi-modal persistent memory system tailored to large language models. It combines a proxy front-end, Model Context Protocol (MCP) server, CLI tooling, scheduled background services, and a SQLite-backed evidence store to keep conversations honest, traceable, and actionable over long-lived workflows.
6+
7+
## Deployment Topology
8+
9+
```
10+
+-------------------------+
11+
| LLM / Agent |
12+
+-----------+-------------+
13+
|
14+
Proxy Mode | MCP Mode (stdin/stdout)
15+
▼
16+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
17+
│ Proxy Server │ │ MCP Server │ │ CLI / Tools │
18+
│ (/v1/chat) │ │ (tinyMem) │ │ (tinymem, │
19+
│ │ │ │ │ dashboards)
20+
└───────┬──────┘ └──────┬───────┘ └──────────────┘
21+
│ │ │
22+
▼ ▼ ▼
23+
┌──────────────────────────────────────────────┐
24+
│ tinyMem Application │
25+
│ - CoreModule - ProjectModule - ServerModule │
26+
│ - Service Layer (Memory, Evidence, Recall) │
27+
└──────────────────┬───────────────────────────┘
28+
▼
29+
+------------------+
30+
| SQLite Memory DB |
31+
+------------------+
32+
▼
33+
+---------------+
34+
| tinyTasks.md |
35+
| (ledger file) |
36+
+---------------+
37+
```
38+
39+
Proxy and MCP transports enqueue requests into the same core process, which routes them through shared services and the SQLite store. The CLI tools and dashboards hook into the same API surface, exposing diagnostics, `tinyTasks` synchronization, and manual memory operations.
40+
41+
## Core Modules and Service Layer
42+
43+
- **CoreModule**: Loads configuration, bootstraps structured logging, and opens the SQLite database used for persistent memories and task state.
44+
- **ProjectModule**: Knows the project root, project ID, and file-system layout so services can locate `tinyTasks.md`, sample data, and per-project metadata.
45+
- **ServerModule**: Understands the execution mode (proxy, MCP, standalone) and wires transports to MCP tool handlers, health endpoints, and the Ralph repair loop.
46+
47+
The service layer sits atop the modules:
48+
49+
- **Memory Service** stores, indexes, and deletes memories while conforming to truth states (verified/asserted/tentative) and allows custom recall tiers.
50+
- **Evidence Service** ensures evidence predicates are evaluated before admitting facts, constraining claims, or closing a Ralph loop.
51+
- **Recall Engine** decides which memories to inject back into prompts based on tiers, tokens, and freshness heuristics.
52+
53+
## Memory Pipeline and Persistence
54+
55+
1. **Ingestion** – Agents issue `memory_write` or CLI commands, specifying type (constraint, plan, decision, observation, note, task, claim). Facts require external evidence references while other types may be more loosely defined.
56+
2. **Evidence gating** – Evidence predicates such as `file_exists`, `cmd_exit0`, or `test_pass` are checked before a discovery is marked `verified`. Unverified assertions stay `asserted` or `tentative` until more proof arrives.
57+
3. **Storage** – SQLite tables store the memory payload, metadata, recall tier, and hash for deduplication. The same store backs tinyTasks-derived state so everything stays in lockstep.
58+
4. **Recall** – The recall engine filters memories by tier (`always`, `contextual`, `opportunistic`), truth state, workspace tags, and temporal relevance before injecting them into responses.
59+
5. **Verification & Updates** – The CLI and MCP expose `memory_stats`, `memory_health`, and `memory_doctor` so operators can inspect database health, run diagnostics, or re-verify stored entries.
60+
61+
## tinyTasks System
62+
63+
`tinyTasks.md` remains the single source of truth for work. tinyMem keeps this ledger synchronized with memory entries and enforces strict intent semantics.
64+
65+
```
66+
┌────────────────────────────────────────────────────────────┐
67+
│ tinyTasks System │
68+
├──────────────┬──────────────┬──────────────┬───────────────┤
69+
│ Parser │ Task Memory │ Synchronizer│ Guardrails │
70+
│ - Reads file │ - Mirrors │ - Watches │ - Intent │
71+
│ - Validates │ unchecked │ file │ policies │
72+
└──────────────┴──────────────┴──────────────┴───────────────┘
73+
```
74+
75+
### Intent semantics
76+
- The system may automatically create `tinyTasks.md` when multi-step work is implied (multi-step requests, missing file detections, or task-related CLI/MCP commands). The auto-created file is intentionally inert and clearly marked `# Tasks — NOT STARTED` so no work is authorized yet.
77+
- Real intent exists only when a human edits the file, replaces the title with a concrete goal, and adds unchecked task list entries (`- [ ]`). The earlier policy ensures deterministic behavior while keeping humans in control.
78+
- When the file contains unchecked human-authored tasks, tinyMem parses, validates, and surfaces them to memory commands; completed tasks (`- [x]`) are ignored unless re-opened.
79+
80+
### File features
81+
- Format: hierarchical Markdown lists with GitHub-style checkboxes for top-level tasks and atomic subtasks.
82+
- Synchronization: CLI/MCP commands read and write `tinyTasks.md`, regenerate memory entries, and drive agent workflows.
83+
- Safety: Dormant unchecked tasks stay out of recall unless explicitly requested, preventing stale instructions from triggering new work.
84+
85+
## Ralph Mode (Autonomous Repair)
86+
87+
Ralph orchestrates evidence-gated repair loops when tasks require verification.
88+
89+
```
90+
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
91+
│ Execute │ -> │ Evidence │ -> │ Recall │ -> │ Repair │
92+
│ Phase │ │ Phase │ │ Phase │ │ Phase │
93+
└──────────┘ └──────────┘ └──────────┘ └──────────┘
94+
↑ │
95+
└───────────────────── Loop control ──────────────────┘
96+
```
97+
98+
- **Execute**: Runs diagnostic commands or tests (via `memory_ralph` API) capturing stdout/stderr.
99+
- **Evidence**: Enforces predicates like `cmd_exit0`, `test_pass`, or `file_exists` before declaring success.
100+
- **Recall**: Fetches relevant memories, including tinyTasks state, to inform repairs.
101+
- **Repair**: Applies fixes (patches, file edits) while respecting forbidden paths, iteration caps, and human approval gates.
102+
103+
Safety measures include iteration limits, forbidden-path enforcement, diagnostics logging, and human gating for high-risk repairs.
104+
105+
## Tooling and Interfaces
106+
107+
tinyMem exposes capabilities through CLI commands, MCP tool calls, and the dashboard.
108+
109+
| Interface | Purpose |
110+
| --- | --- |
111+
| `tinymem` CLI | Launches commands such as `memory_query`, `memory_recent`, `memory_write`, `memory_stats`, `memory_doctor`, `dashboard`, `proxy`, and `mcp` for dev workflows. |
112+
| MCP tools | `memory_query`, `memory_recent`, `memory_write`, `memory_stats`, `memory_health`, `memory_doctor`, `memory_ralph`, and others feed LLM agents. |
113+
| Proxy endpoints | `/v1/chat/completions` (OpenAI-compatible) forwards requests through tinyMem to enforce recall and filtering. |
114+
| Dashboard | Visualizes memory state, tinyTasks progress, and health signals to operators. |
115+
116+
All interfaces observe the same architecture, retrieving memories, verifying evidence, and updating tinyTasks, so every agent or operator experiences a consistent view of project state.
117+
118+
## Operational Notes
119+
120+
- Versioned container images (e.g., GHCR) package the tinyMem binary along with schema migrations and dashboards.
121+
- Diagnostics (`tinyMem doctor`, `memory_doctor`) report on schema health, memory integrity, and task sync status.
122+
- The architecture ensures persistence, transparency, and evidence-backed memory retrieval for long-lived multi-agent workflows.

0 commit comments

Comments
 (0)