memory
Persistent Memory System
Overview
Memory lives in .aiter/memory/ relative to the project root. Each file has a specific format and purpose. Files use Markdown with YAML frontmatter for metadata.
Core principle: Memory files are the single source of truth for agent state. All agents (orchestrator, heartbeat, support-responder, monitor) read and write to the same memory files. This enables cross-layer composability.
Directory Structure
.aiter/
└── memory/
├── tasks.md # Pending, in-progress, completed tasks
├── knowledge.md # Learned facts and preferences
├── contacts.md # IM channels and people
├── journal.md # Activity log
├── orchestration.md # Active multi-project state
├── monitors.md # Service monitoring config
├── config.md # Agent configuration
└── archive/ # Archived old entries
└── tasks-2024-01.md
File Formats
tasks.md — Task Management
---
type: task-list
updated: 2024-01-15T10:30:00Z
---
## Pending
### [HIGH] Deploy v2.1 to staging
- due: 2024-01-15 14:00
- assigned: heartbeat
- created: 2024-01-14
- tags: deployment, staging
- notes: Run tests first, then deploy via CI/CD
- action: cd ecommerce-backend && npm test && npm run deploy:staging
### [NORMAL] Generate weekly report
- due: 2024-01-15 09:00 (recurring: 0 9 * * MON)
- assigned: heartbeat
- cronJobId: cron-abc123
- tags: reporting, weekly
- action: Gather git log, test results, metrics. Send to Slack.
### [LOW] Update README with new API docs
- due: 2024-01-20
- assigned: user
- tags: documentation
- notes: Low priority, do when convenient
## In Progress
### [HIGH] Monitor API latency
- started: 2024-01-15 10:00
- assigned: monitor-guardian
- orchestrationId: orch-xyz789
- progress: 45%
- tags: monitoring, api
- lastUpdate: Checking endpoint response times
## Completed (last 7 days)
### [NORMAL] Set up CI pipeline
- completed: 2024-01-14 16:30
- assigned: heartbeat
- tags: ci, github-actions
- outcome: GitHub Actions workflow created, runs on push to main
Task fields:
| Field | Required | Description |
|---|---|---|
| Priority | Yes | [HIGH], [NORMAL], or [LOW] in heading |
| due | No | ISO date, or recurring: <cron> |
| assigned | No | Agent name or user |
| created | Yes | ISO date |
| tags | No | Comma-separated categories |
| cronJobId | No | Link to cron job if scheduled |
| orchestrationId | No | Link to orchestration plan |
| action | No | Specific command/action to take |
| notes | No | Additional context |
| progress | No | Percentage (in-progress only) |
| outcome | No | Result description (completed only) |
knowledge.md — Knowledge Base
---
type: knowledge-base
updated: 2024-01-15T10:30:00Z
---
## User Preferences
- Prefers PostgreSQL over MongoDB
- Uses TailwindCSS for styling
- Wants tests for all critical paths
- Commit messages in English, conventional format
- Prefers TypeScript over JavaScript
## Project Knowledge
### E-commerce Platform
- Frontend: React 18 + TypeScript + Vite
- Backend: Node.js + Express + PostgreSQL
- Deploy: GitHub Actions → staging → production
- CI: Tests must pass before merge
### Marketing Site
- Framework: Next.js 14 with App Router
- CMS: Contentful
- Hosting: Vercel
## Technical Facts
- Deploy script: `npm run deploy:staging`
- CI pipeline takes ~8 minutes
- Database backup runs at 2 AM daily
- Staging URL: https://staging.example.com
- Production URL: https://example.com
## Decisions Made
- 2024-01-10: Chose JWT over session cookies for auth (stateless, mobile-friendly)
- 2024-01-12: Using Redis for caching (existing infrastructure)
- 2024-01-14: Monorepo rejected — separate repos for frontend/backend
contacts.md — Communication Directory
---
type: contacts
updated: 2024-01-15T10:30:00Z
---
## Channels
| Name | ID | Type | Status |
|------|-----|------|--------|
| Dev Team Bot | channel-abc123 | telegram | connected |
| Slack Alerts | channel-def456 | webhook | disconnected |
| DingTalk Team | channel-ghi789 | webhook | connected |
## Message Routes
| Channel | Project | Prefix | Terminal |
|---------|---------|--------|----------|
| Dev Team Bot | project-123 | /ask | auto |
| Dev Team Bot | project-456 | /deploy | auto |
## People
- **Alice** (PM): Reach via Telegram Dev Team Bot, prefers morning updates
- **Bob** (DevOps): Reach via Slack Alerts, on-call weekdays
- **Carol** (Designer): Reach via DingTalk, responds within 1 hour
journal.md — Activity Log
---
type: activity-journal
---
## 2024-01-15
### 10:30 — Heartbeat Check
- 2 pending tasks found
- Executed: "Generate weekly report" → sent to Slack ✓
- Deferred: "Deploy v2.1" (due at 14:00)
### 10:45 — IM Response
- From: Alice via Telegram
- Request: "What's the API latency?"
- Action: Ran curl to check /health endpoint, latency 120ms
- Reply: "API latency is 120ms (normal range 50-200ms)"
### 11:00 — Orchestration Update
- Plan "E-commerce Platform" Phase 2: 65% complete
- t3 (auth API): 65% done, JWT refresh logic in progress
- Sent progress notification to Telegram
### 11:30 — Monitor Alert
- API endpoint /products returned 503 (1 occurrence)
- Auto-remediation: Restarted pm2 process
- Verified: Endpoint recovered, now returning 200
- Notification sent: "API recovered after auto-restart"
## 2024-01-14
### 16:30 — Task Completed
- "Set up CI pipeline" completed
- Created .github/workflows/ci.yml
- Tests run on push to main and PR branches
- Moved to Completed section in tasks.md
monitors.md — Service Monitoring
---
type: monitor-config
updated: 2024-01-15T10:00:00Z
---
## Monitors
### API Health Check
- type: http
- url: https://api.example.com/health
- interval: */5 * * * * (every 5 min)
- cronJobId: cron-mon-001
- threshold: status != 200
- alertPriority: high
- autoRemediate: pm2 restart api-server
- lastCheck: 2024-01-15T10:30:00Z
- lastStatus: healthy
### Database Connection
- type: command
- command: pg_isready -h localhost -p 5432
- interval: */10 * * * * (every 10 min)
- cronJobId: cron-mon-002
- threshold: exit code != 0
- alertPriority: high
- autoRemediate: systemctl restart postgresql
- lastCheck: 2024-01-15T10:30:00Z
- lastStatus: healthy
### Disk Space
- type: command
- command: df -h / | awk 'NR==2 {print $5}' | tr -d '%'
- interval: 0 * * * * (every hour)
- cronJobId: cron-mon-003
- threshold: value > 90
- alertPriority: normal
- autoRemediate: null (notify only)
- lastCheck: 2024-01-15T10:00:00Z
- lastStatus: healthy (72% used)
config.md — Agent Configuration
---
type: agent-config
setupComplete: true
setupDate: 2024-01-14T09:00:00Z
---
## Heartbeat
- expression: */30 * * * *
- cronJobId: cron-heartbeat-001
- projectId: project-123
## Default Notification
- target: im
- channelId: channel-abc123
- priority: normal
## IM Configuration
- primaryChannel: channel-abc123 (Telegram)
- secondaryChannel: channel-def456 (Slack)
## Memory Maintenance
- archiveCompletedAfterDays: 7
- pruneJournalAfterDays: 30
- maxJournalEntries: 500
Reading Memory
Use the Read tool to read memory files:
Read .aiter/memory/tasks.md
For targeted searches, use the Grep tool:
Grep for "due: 2024-01-15" in .aiter/memory/tasks.md
Grep for "PostgreSQL" in .aiter/memory/knowledge.md
Grep for "Alice" in .aiter/memory/contacts.md
Writing Memory
Adding a new task
Use the Edit tool to insert under ## Pending:
### [NORMAL] New task title
- due: 2024-01-16 10:00
- assigned: heartbeat
- created: 2024-01-15
- tags: feature
- action: Description of what to do
Updating task status
Use the Edit tool to move task from ## Pending to ## In Progress (add started and progress fields) or to ## Completed (add completed and outcome fields).
Adding a journal entry
Use the Edit tool to insert a new entry at the top of today's date section:
### HH:MM — Action Type
- Context details
- Actions taken
- Results
Adding knowledge
Use the Edit tool to append to the appropriate section in knowledge.md.
Memory Maintenance Rules
| Rule | Action |
|---|---|
| Tasks completed >7 days ago | Move to .aiter/memory/archive/tasks-YYYY-MM.md |
| Journal entries >30 days old | Prune from journal.md (keep in archive) |
| Journal exceeds 500 entries | Prune oldest entries |
| Knowledge entries | Never auto-delete |
| Contacts | Never auto-delete |
| Orchestration completed | Clear after 24 hours, archive plan |
| Monitor config | Never auto-delete |
Archive pattern
# Move January completed tasks to archive
mkdir -p .aiter/memory/archive
# Use Edit tool to cut completed entries from tasks.md
# Use Write tool to append to archive/tasks-2024-01.md
Initialization
When memory directory doesn't exist, create it with empty templates:
mkdir -p .aiter/memory/archive
Then use Write tool to create each file with its frontmatter template (empty sections).
More from within-7/aiter
notifications
Multi-target notification system. Send app, IM, and webhook notifications with priority levels, quiet hours, and history tracking.
2tunnels
Tunnel lifecycle management. Create, monitor, and close tunnels for sharing local services publicly. Integrate with file servers for report and preview sharing.
1aiter-control
Control AiTer terminal client via CLI commands. Create projects, manage terminals, read/write terminal output, and coordinate multi-agent workflows.
1reporting
Report generation and distribution. Gather data from multiple sources, format structured reports, and distribute via IM, notifications, or shared tunnel URLs.
1orchestration
Multi-project orchestration patterns. Plan format, inter-agent communication protocol, dispatch workflow, task templates, monitoring loops, and persistent state tracking via memory files.
1platform-core
Foundation skill for the AiTer Agent Platform. Provides identity framework, autonomous decision rules, environment detection, full AiTer CLI command reference across all 11 namespaces, and persistent memory basics.
1