Skip to content

Commit 169900b

Browse files
tpaetpae
committed
updated docs
1 parent 162dea8 commit 169900b

File tree

3 files changed

+466
-0
lines changed

3 files changed

+466
-0
lines changed

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ Osaurus is the AI edge runtime for macOS. It brings together:
6060
- **Remote MCP Providers** — Connect to external MCP servers and aggregate their tools
6161
- **Plugin System** — Extend functionality with community and custom tools
6262
- **Agents** — Create custom AI assistants with unique prompts, tools, and visual themes
63+
- **Memory** — 4-layer memory system that learns from conversations with profile, working memory, summaries, and knowledge graph
6364
- **Skills** — Import reusable AI capabilities from GitHub or files ([Agent Skills](https://agentskills.io/) compatible)
6465
- **Schedules** — Automate recurring AI tasks with timed execution
6566
- **Watchers** — Monitor folders for changes and trigger AI tasks automatically
@@ -85,6 +86,7 @@ Osaurus is the AI edge runtime for macOS. It brings together:
8586
| **Tools & Plugins** | Browser automation, file system, git, web search, and more |
8687
| **Skills** | Import AI capabilities from GitHub or files, with smart context saving |
8788
| **Agents** | Custom AI assistants with unique prompts, tools, and themes |
89+
| **Memory** | Persistent memory with user profile, knowledge graph, and hybrid search|
8890
| **Schedules** | Automate AI tasks with daily, weekly, monthly, or yearly runs |
8991
| **Watchers** | Monitor folders and trigger AI tasks on file system changes |
9092
| **Work Mode** | Autonomous multi-step task execution with parallel task support |
@@ -241,6 +243,36 @@ Use cases:
241243

242244
Access via Management window (`⌘ Shift M`) → **Agents**.
243245

246+
### Memory
247+
248+
Osaurus remembers what matters across conversations using a 4-layer memory system that runs entirely in the background.
249+
250+
**Layers:**
251+
252+
- **User Profile** — An auto-generated summary of who you are, updated as conversations accumulate. Add explicit overrides for facts the AI should always know.
253+
- **Working Memory** — Structured entries (facts, preferences, decisions, corrections, commitments, relationships, skills) extracted from every conversation turn.
254+
- **Conversation Summaries** — Compressed recaps of past sessions, generated automatically after periods of inactivity.
255+
- **Knowledge Graph** — Entities and relationships extracted from conversations, searchable by name or relation type.
256+
257+
**Features:**
258+
259+
- **Automatic Extraction** — Memories are extracted from each conversation turn using an LLM, with no manual effort required
260+
- **Hybrid Search** — BM25 + vector embeddings (via VecturaKit) with MMR reranking for relevant, diverse recall
261+
- **Verification Pipeline** — 3-layer deduplication and contradiction detection prevents redundant or conflicting memories
262+
- **Per-Agent Isolation** — Each agent maintains its own memory entries and summaries
263+
- **Configurable Budgets** — Control token allocation for profile, working memory, summaries, and graph in the system prompt
264+
- **Non-Blocking** — All extraction and indexing runs in the background without slowing down chat
265+
266+
**Use Cases:**
267+
268+
- Remember your coding preferences, project context, and tool choices across sessions
269+
- Build a personal knowledge base from ongoing research conversations
270+
- Maintain continuity with multiple agents that each learn your domain-specific needs
271+
272+
Access via Management window (`⌘ Shift M`) → **Memory**.
273+
274+
See [Memory Guide](docs/MEMORY.md) for details.
275+
244276
### Skills
245277

246278
Extend your AI with reusable capabilities imported from GitHub or local files.

‎docs/FEATURES.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
1616
| MCP Server | Stable | "MCP Server" | (in README) | Networking/OsaurusServer.swift, Services/MCPServerManager.swift |
1717
| Tools & Plugins | Stable | "Tools & Plugins" | PLUGIN_AUTHORING.md | Tools/, Managers/PluginManager.swift |
1818
| Skills | Stable | "Skills" | SKILLS.md | Managers/SkillManager.swift, Views/SkillsView.swift, Services/CapabilityService.swift |
19+
| Memory | Stable | "Key Features" | MEMORY.md | Services/MemoryService.swift, Services/MemorySearchService.swift, Services/MemoryContextAssembler.swift |
1920
| Agents | Stable | "Agents" | (in README) | Managers/AgentManager.swift, Models/Agent.swift, Views/AgentsView.swift |
2021
| Schedules | Stable | "Schedules" | (in README) | Managers/ScheduleManager.swift, Models/Schedule.swift, Views/SchedulesView.swift |
2122
| Watchers | Stable | "Watchers" | WATCHERS.md | Managers/WatcherManager.swift, Models/Watcher.swift, Views/WatchersView.swift |
@@ -55,6 +56,7 @@ Canonical reference for all Osaurus features, their status, and documentation.
5556
│ │ ├── ToolsManagerView (Tools) │
5657
│ │ ├── AgentsView (Agents) │
5758
│ │ ├── SkillsView (Skills) │
59+
│ │ ├── MemoryView (Memory) │
5860
│ │ ├── SchedulesView (Schedules) │
5961
│ │ ├── WatchersView (Watchers) │
6062
│ │ ├── ThemesView (Themes) │
@@ -98,6 +100,11 @@ Canonical reference for all Osaurus features, their status, and documentation.
98100
│ │ ├── VADService (Voice activity detection, wake-word) │
99101
│ │ ├── TranscriptionModeService (Global dictation into any app) │
100102
│ │ └── AudioInputManager (Microphone/system audio selection) │
103+
│ ├── Memory │
104+
│ │ ├── MemoryService (Conversation processing and extraction) │
105+
│ │ ├── MemorySearchService (Hybrid BM25 + vector search) │
106+
│ │ ├── MemoryContextAssembler (Context injection with budgets) │
107+
│ │ └── MemoryDatabase (SQLite storage with migrations) │
101108
│ └── Utilities │
102109
│ ├── InsightsService (Request logging) │
103110
│ ├── HuggingFaceService (Model downloads) │
@@ -757,6 +764,111 @@ A context optimization system that reduces token usage by ~80%:
757764

758765
---
759766

767+
### Memory
768+
769+
**Purpose:** Persistent, multi-layer memory system that extracts, stores, and retrieves knowledge from conversations to provide personalized, context-aware AI interactions.
770+
771+
**Components:**
772+
773+
- `Services/MemoryService.swift` — Core actor for conversation processing, extraction, and summarization
774+
- `Services/MemorySearchService.swift` — Hybrid search (BM25 + vector) with MMR reranking
775+
- `Services/MemoryContextAssembler.swift` — Assembles memory context for system prompt injection
776+
- `Storage/MemoryDatabase.swift` — SQLite database with WAL mode and schema migrations
777+
- `Models/MemoryModels.swift` — Data types for all 4 memory layers
778+
- `Models/MemoryConfiguration.swift` — User-configurable settings with validation
779+
- `Views/MemoryView.swift` — Memory management UI (profile, overrides, agents, statistics, config)
780+
781+
**4-Layer Architecture:**
782+
783+
| Layer | Type | Purpose | Retention |
784+
|-------|------|---------|-----------|
785+
| Layer 1 | User Profile | Auto-generated user summary with version tracking | Permanent |
786+
| Layer 2 | Working Memory | Structured entries (facts, preferences, decisions, etc.) | Per-agent limit (default 500) |
787+
| Layer 3 | Conversation Summaries | Compressed session recaps | Configurable (default 7 days) |
788+
| Layer 4 | Conversation Chunks | Raw conversation turns | Permanent |
789+
790+
**Memory Entry Types:**
791+
792+
| Type | Description |
793+
|------|-------------|
794+
| `fact` | Factual information about the user or their environment |
795+
| `preference` | User preferences and likes/dislikes |
796+
| `decision` | Decisions made during conversations |
797+
| `correction` | Corrections to previous information |
798+
| `commitment` | Promises or plans the user mentioned |
799+
| `relationship` | Relationships between people, projects, or concepts |
800+
| `skill` | Skills, expertise, or knowledge areas |
801+
802+
**Knowledge Graph:**
803+
804+
- Entities: person, company, place, project, tool, concept, event
805+
- Relationships with confidence scores and temporal validity
806+
- Graph traversal search by entity name or relation type
807+
808+
**Search & Retrieval:**
809+
810+
| Method | Backend | Fallback |
811+
|--------|---------|----------|
812+
| Hybrid search | VecturaKit (BM25 + vector embeddings) | SQLite LIKE queries |
813+
| MMR reranking | Jaccard similarity for diversity | N/A |
814+
815+
- Default MMR lambda: 0.7 (relevance vs. diversity tradeoff)
816+
- Default fetch multiplier: 2.0x over-fetch before reranking
817+
818+
**Verification Pipeline (3 layers, no LLM calls):**
819+
820+
| Layer | Method | Threshold |
821+
|-------|--------|-----------|
822+
| Layer 1 | Jaccard word-overlap deduplication | 0.6 |
823+
| Layer 2 | Contradiction detection (same type + similarity) | 0.3 |
824+
| Layer 3 | Semantic similarity via vector search | 0.85 |
825+
826+
**Context Assembly:**
827+
828+
Memory is injected into system prompts in this order with per-section token budgets:
829+
830+
| Section | Default Budget |
831+
|---------|---------------|
832+
| User Overrides | (always included) |
833+
| User Profile | 2,000 tokens |
834+
| Working Memory | 500 tokens |
835+
| Conversation Summaries | 1,000 tokens |
836+
| Key Relationships | 300 tokens |
837+
838+
Results are cached for 10 seconds per agent.
839+
840+
**Resilience:**
841+
842+
- Circuit breaker: opens after 5 consecutive failures, 60-second cooldown
843+
- Retry logic: exponential backoff (1s, 2s, 4s), max 3 retries, 60-second timeout
844+
- Actor-based concurrency for thread safety
845+
- Non-blocking: all extraction runs in the background
846+
847+
**Configuration:**
848+
849+
| Setting | Default | Range |
850+
|---------|---------|-------|
851+
| `coreModelProvider` | `anthropic` | Any provider |
852+
| `coreModelName` | `claude-haiku-4-5` | Any model |
853+
| `embeddingBackend` | `mlx` | `mlx`, `none` |
854+
| `embeddingModel` | `nomic-embed-text-v1.5` | Any embedding model |
855+
| `summaryDebounceSeconds` | 60 | 10 -- 3,600 |
856+
| `profileMaxTokens` | 2,000 | 100 -- 50,000 |
857+
| `profileRegenerateThreshold` | 10 | 1 -- 100 |
858+
| `workingMemoryBudgetTokens` | 500 | 50 -- 10,000 |
859+
| `summaryRetentionDays` | 7 | 1 -- 365 |
860+
| `summaryBudgetTokens` | 1,000 | 50 -- 10,000 |
861+
| `graphBudgetTokens` | 300 | 50 -- 5,000 |
862+
| `recallTopK` | 10 | 1 -- 100 |
863+
| `mmrLambda` | 0.7 | 0.0 -- 1.0 |
864+
| `mmrFetchMultiplier` | 2.0 | 1.0 -- 10.0 |
865+
| `maxEntriesPerAgent` | 500 | 0 -- 10,000 |
866+
| `enabled` | true | true/false |
867+
868+
**Storage:** `~/.osaurus/memory/memory.db` (SQLite with WAL mode)
869+
870+
---
871+
760872
## Documentation Index
761873

762874
| Document | Purpose |
@@ -770,6 +882,7 @@ A context optimization system that reduces token usage by ~80%:
770882
| [DEVELOPER_TOOLS.md](DEVELOPER_TOOLS.md) | Insights and Server Explorer guide |
771883
| [VOICE_INPUT.md](VOICE_INPUT.md) | Voice input, WhisperKit, and VAD mode guide |
772884
| [SKILLS.md](SKILLS.md) | Skills and capability selection guide |
885+
| [MEMORY.md](MEMORY.md) | Memory system and configuration guide |
773886
| [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) | Creating custom plugins |
774887
| [OpenAI_API_GUIDE.md](OpenAI_API_GUIDE.md) | API usage, tool calling, streaming |
775888
| [SHARED_CONFIGURATION_GUIDE.md](SHARED_CONFIGURATION_GUIDE.md) | Shared configuration for teams |

0 commit comments

Comments
 (0)