docs: split README into component docs, update jobkit dep
- Break README into README.md (overview), docs/daemon.md (pipeline stages, diagnostics, common issues), docs/notifications.md (notification daemon, IRC/Telegram modules) - Update jobkit dependency from local path to git URL Co-Authored-By: ProofOfConcept <poc@bcachefs.org>
This commit is contained in:
Kent Overstreet
parent
45335de220
commit
908f8c9e52
5 changed files with 228 additions and 129 deletions
145
README.md
145
README.md
|
|
@ -28,17 +28,12 @@ detection.
|
|||
|
||||
### Background agents
|
||||
|
||||
A background daemon (`poc-memory daemon`) automatically spawns agents
|
||||
for memory maintenance:
|
||||
See [docs/daemon.md](docs/daemon.md) for full daemon documentation.
|
||||
|
||||
- **Experience mining** — when a session ends, extracts experiences
|
||||
and observations from the transcript into journal entries
|
||||
- **Fact extraction** — pulls concrete facts (names, dates, decisions,
|
||||
preferences) into structured knowledge nodes
|
||||
- **Consolidation** — periodic graph health work: replay queues
|
||||
(spaced repetition), interference detection (contradictory nodes),
|
||||
hub differentiation (splitting overloaded nodes), triangle closure
|
||||
(connecting nodes that share neighbors), and orphan linking
|
||||
A background daemon (`poc-memory daemon`) automatically processes
|
||||
session transcripts through experience-mine (journal extraction)
|
||||
and fact-mine (structured knowledge extraction) stages, with
|
||||
segment-aware splitting for large multi-compaction sessions.
|
||||
|
||||
### Neuroscience-inspired algorithms
|
||||
|
||||
|
|
@ -64,66 +59,12 @@ recall and relevance.
|
|||
|
||||
## Notification system
|
||||
|
||||
A separate daemon (`poc-daemon`) routes messages from communication
|
||||
modules and internal events through a hierarchical, activity-aware
|
||||
delivery system.
|
||||
See [docs/notifications.md](docs/notifications.md) for full
|
||||
notification daemon documentation.
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
Communication modules Hooks
|
||||
┌──────────────────┐ ┌─────────────┐
|
||||
│ IRC (native) │──┐ │ poc-hook │
|
||||
│ Telegram (native│ │ mpsc │ (all events)│
|
||||
└──────────────────┘ ├──────┐ └──────┬───────┘
|
||||
│ │ │
|
||||
▼ │ capnp-rpc
|
||||
┌───────────┘ │
|
||||
│ poc-daemon │
|
||||
│ │
|
||||
│ NotifyState ◄─────────┘
|
||||
│ ├── type registry
|
||||
│ ├── pending queue
|
||||
│ ├── threshold lookup
|
||||
│ └── activity-aware delivery
|
||||
│
|
||||
│ idle::State
|
||||
│ ├── presence detection
|
||||
│ ├── sleep/wake/dream modes
|
||||
│ └── tmux prompt injection
|
||||
└────────────────────────
|
||||
```
|
||||
|
||||
### Notification types and urgency
|
||||
|
||||
Types are free-form hierarchical strings: `irc.mention.nick`,
|
||||
`irc.channel.bcachefs`, `telegram.kent`. Each has an urgency level:
|
||||
|
||||
| Level | Name | Meaning |
|
||||
|-------|---------|--------------------------------------|
|
||||
| 0 | ambient | Include in idle context only |
|
||||
| 1 | low | Deliver on next check |
|
||||
| 2 | normal | Deliver on next user interaction |
|
||||
| 3 | urgent | Interrupt immediately |
|
||||
|
||||
Per-type thresholds walk up the hierarchy: `irc.channel.bcachefs-ai`
|
||||
→ `irc.channel` → `irc` → default. Effective thresholds adjust by
|
||||
activity state: raised when focused, lowered when idle, only urgent
|
||||
when sleeping.
|
||||
|
||||
### Communication modules
|
||||
|
||||
**IRC** — native async TLS connection (tokio-rustls). Connects,
|
||||
joins channels, parses messages, generates notifications. Runtime
|
||||
commands: join, leave, send, status, log, nick. Per-channel logs
|
||||
at `~/.claude/irc/logs/`.
|
||||
|
||||
**Telegram** — native async HTTP long-polling (reqwest). Downloads
|
||||
media (photos, voice, documents). Chat ID filtering for security.
|
||||
Runtime commands: send, status, log.
|
||||
|
||||
Both modules persist config changes to `~/.claude/daemon.toml` —
|
||||
channel joins and nick changes survive restarts.
|
||||
`poc-daemon` routes messages from IRC (native async TLS) and
|
||||
Telegram (native async HTTP) through a hierarchical, activity-aware
|
||||
delivery system with urgency levels and per-type thresholds.
|
||||
|
||||
## Quick start
|
||||
|
||||
|
|
@ -174,27 +115,6 @@ reads directly from disk rather than the store.
|
|||
|
||||
Override: `POC_MEMORY_CONFIG=/path/to/config.jsonl`
|
||||
|
||||
### Notification daemon
|
||||
|
||||
Config: `~/.claude/daemon.toml`
|
||||
|
||||
```toml
|
||||
[irc]
|
||||
enabled = true
|
||||
server = "irc.oftc.net"
|
||||
port = 6697
|
||||
tls = true
|
||||
nick = "MyBot"
|
||||
user = "bot"
|
||||
realname = "My Bot"
|
||||
channels = ["#mychannel"]
|
||||
|
||||
[telegram]
|
||||
enabled = true
|
||||
token = "bot-token-here"
|
||||
chat_id = 123456789
|
||||
```
|
||||
|
||||
### Hooks
|
||||
|
||||
Configured in `~/.claude/settings.json`:
|
||||
|
|
@ -231,6 +151,8 @@ poc-memory categorize KEY CAT # core/tech/gen/obs/task
|
|||
|
||||
poc-memory journal-write "text" # Write a journal entry
|
||||
poc-memory journal-tail [N] # Last N entries (default 20)
|
||||
--full # Show full content (not truncated)
|
||||
--level=daily|weekly|monthly # Show digest level
|
||||
|
||||
poc-memory used KEY # Boost weight (was useful)
|
||||
poc-memory wrong KEY [CTX] # Reduce weight (was wrong)
|
||||
|
|
@ -244,47 +166,13 @@ poc-memory load-context # Output session-start context
|
|||
poc-memory load-context --stats # Context size breakdown
|
||||
```
|
||||
|
||||
### Notification daemon
|
||||
|
||||
```bash
|
||||
poc-daemon # Start daemon
|
||||
poc-daemon status # State summary
|
||||
poc-daemon irc status # IRC module status
|
||||
poc-daemon irc send TARGET MSG # Send IRC message
|
||||
poc-daemon irc join CHANNEL # Join (persists to config)
|
||||
poc-daemon irc leave CHANNEL # Leave
|
||||
poc-daemon irc log [N] # Last N messages
|
||||
poc-daemon telegram status # Telegram module status
|
||||
poc-daemon telegram send MSG # Send Telegram message
|
||||
poc-daemon telegram log [N] # Last N messages
|
||||
poc-daemon notify TYPE URG MSG # Submit notification
|
||||
poc-daemon notifications [URG] # Get + drain pending
|
||||
poc-daemon notify-types # List all types
|
||||
poc-daemon notify-threshold T L # Set per-type threshold
|
||||
poc-daemon sleep / wake / quiet # Session management
|
||||
poc-daemon stop # Shut down
|
||||
```
|
||||
|
||||
### Mining (used by background daemon)
|
||||
|
||||
```bash
|
||||
poc-memory experience-mine PATH # Extract experiences from transcript
|
||||
poc-memory fact-mine-store PATH # Extract and store facts
|
||||
poc-memory experience-mine PATH [--segment N] # Extract experiences
|
||||
poc-memory fact-mine-store PATH # Extract and store facts
|
||||
```
|
||||
|
||||
## How the hooks work
|
||||
|
||||
**memory-search** (UserPromptSubmit):
|
||||
1. First prompt or post-compaction: loads full memory context via
|
||||
`poc-memory load-context`
|
||||
2. Every prompt: keyword search, returns relevant memories as
|
||||
additionalContext. Deduplicates across the session.
|
||||
|
||||
**poc-hook** (UserPromptSubmit, PostToolUse, Stop):
|
||||
- Signals user activity and responses to poc-daemon
|
||||
- Drains pending notifications into additionalContext
|
||||
- Monitors context window usage, warns before compaction
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Store**: Append-only Cap'n Proto log with in-memory cache. Nodes
|
||||
|
|
@ -296,9 +184,10 @@ poc-memory fact-mine-store PATH # Extract and store facts
|
|||
- **Neuro**: Spectral embedding, consolidation scoring, replay
|
||||
queues, interference detection, hub differentiation.
|
||||
- **Daemon (memory)**: jobkit-based task scheduling with
|
||||
resource-gated LLM access.
|
||||
resource-gated LLM access. See [docs/daemon.md](docs/daemon.md).
|
||||
- **Daemon (notify)**: Cap'n Proto RPC over Unix socket, tokio
|
||||
LocalSet with native async IRC and Telegram modules.
|
||||
LocalSet with native async IRC and Telegram modules. See
|
||||
[docs/notifications.md](docs/notifications.md).
|
||||
|
||||
## For AI assistants
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue