AutoGineer
Generated banner for Baalda
Generated logo for Baalda

Baalda

Memory framework

First committed by naveedharri

Published in naveedharri/baalda. Publisher page

327 GitHub stars

What it is

The team second brain. Plain Markdown files on your disk, edited together in real time, and read and written by your AI like a teammate.
— the description by naveedharri

Summary from the brain’s metadata

The team second brain. Plain Markdown files on your disk, edited together in real time, and read and written by your AI like a teammate.

How it works

Memory model: SQL database

AutoGineer overview, from the brain’s own files

Memory model: SQL database. Folders: .claude (agent config, 7 files); .github (agent config, 8 files); app (source code, 1593 files); docs (docs, 24 files); scripts (scripts, 6 files). The agent reads CLAUDE.md, list_skills, get_skill, read_skill_file, list_folders. The agent writes write_note_if_missing, append_note, delete_folder, create_note, update_note.

Folders
FolderRoleFiles
.claudeagent-config7
.githubagent-config8
appsource-code1593
docsdocs24
scriptsscripts6
.agentsfolder2
deployfolder7
eefolder2

The agent reads

The agent writes

Requirements

Databases: PostgreSQL, SQLite

API keys (by name): CONTEXT_MCP_TOKEN, JWT_SECRET

Works with: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Kiro, OpenCode, Amp, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerThe author’s README also describes installing it with Docker Compose. Read its install section: AutoGineer did not scan that path. https://github.com/naveedharri/baalda/blob/90929b5a68de3f5347cbf2084ee672dd41264234/README.md#prefer-not-to-run-a-server

  2. First committed by naveedharri. Published in naveedharri/baalda. Licence: Apache License 2.0.

Usage

AutoGineer’s guidance for this type of brain

Install the library in your own agent code and call it to store and retrieve memories; see its documentation for the API.

Documentation by naveedharri

A licence file holds personal contact details, so AutoGineer links to the files instead of copying them. Read the documentation at the source

512 files · 512 not served here

Advantages

  • Local-first: the memory stays in files or a database on your own machine (a rule-derived fact from the brain’s files, evidence: README.md)
  • Open licence (Apache-2.0) (a rule-derived fact from the brain’s files)

Limitations

  • Needs an API key (CONTEXT_MCP_TOKEN, JWT_SECRET) (a rule-derived fact from the brain’s files, evidence: README.md)
  • Needs a database (PostgreSQL, SQLite) (a rule-derived fact from the brain’s files, evidence: README.md)
  • Link-only: AutoGineer links to the files instead of serving them (a rule-derived fact from the brain’s files)

Security

Risk level: Medium risk

This brain runs

Agent instructions that run or fetch something (61)

  • .agents/skills/relaunch/SKILL.md: Desktop launch: `pnpm run dev:desktop` (= `pnpm --filter desktop tauri dev`;
  • .agents/skills/relaunch/SKILL.md: Server launch: `pnpm run dev` from `app/apps/server/` (tsx watch;
  • .agents/skills/relaunch/SKILL.md: Skip shutdown if none run.
  • .agents/skills/relaunch/SKILL.md: docker ps --filter "publish=5439" --format "{{.Names}} {{.Status}}" || true
  • .agents/skills/relaunch/SKILL.md: # If nothing is listed, from app/apps/server/ run: pnpm run db:up
  • .agents/skills/relaunch/SKILL.md: cd app/apps/server && pnpm run dev
  • .agents/skills/relaunch/SKILL.md: cd app && pnpm run dev:desktop
  • .agents/skills/relaunch/SKILL.md: **Server** (wait ~3–5s): `curl -s http://localhost:3010/health` returns OK, and the task output shows the HTTP :3010 / Hocuspocus WS listeners started. · uses the network
  • .agents/skills/relaunch/SKILL.md: Only `pnpm test` in `apps/server` wipes the DB.
  • .agents/skills/window-simulator/SKILL.md: Install dependencies with `pnpm install` in `app/` if needed.
  • .agents/skills/window-simulator/SKILL.md: pnpm run simulate:windows
  • .agents/skills/window-simulator/SKILL.md: pnpm run simulate:macos
  • .agents/skills/window-simulator/SKILL.md: pnpm exec vitest run <test-files>
  • .agents/skills/window-simulator/SKILL.md: pnpm exec tsc --noEmit
  • .agents/skills/window-simulator/SKILL.md: TAURI_ENV_PLATFORM=windows pnpm run build
  • .claude/skills/baalda-guide/SKILL.md: If you are not inside the repository, fetch the same paths from `https://raw.githubusercontent.com/naveedharri/baalda/main/`; · uses the network
  • .claude/skills/relaunch/SKILL.md: Desktop launch: `pnpm run dev:desktop` (= `pnpm --filter desktop tauri dev --config src-tauri/tauri.dev.conf.json`;
  • .claude/skills/relaunch/SKILL.md: Server launch: `pnpm run dev` from `app/apps/server/` (tsx watch;
  • .claude/skills/relaunch/SKILL.md: docker ps --filter "publish=5439" --format "{{.Names}} {{.Status}}" || true
  • .claude/skills/relaunch/SKILL.md: # If nothing is listed, from app/apps/server/ run: pnpm run db:up
  • .claude/skills/relaunch/SKILL.md: Run in the **background** from the server dir.
  • .claude/skills/relaunch/SKILL.md: cd /Users/macbook/Documents/OpenSource/Baalda/app/apps/server && pnpm run dev
  • .claude/skills/relaunch/SKILL.md: Run in the **background** from the app root.
  • .claude/skills/relaunch/SKILL.md: cd /Users/macbook/Documents/OpenSource/Baalda/app && pnpm run dev:desktop
  • .claude/skills/relaunch/SKILL.md: **Server** (wait ~3–5s): `curl -s http://localhost:3010/health` returns OK, and the task output shows the HTTP :3010 / Hocuspocus WS listeners started. · uses the network
  • .claude/skills/relaunch/SKILL.md: Only `pnpm test` in `apps/server` wipes the DB.
  • AGENTS.md: Install dependencies with `pnpm install` from `app/` (activate Corepack if needed).
  • AGENTS.md: | Task | Directory | Command | | --- | --- | --- | | Desktop development | `app/` | `pnpm run dev:desktop` | | Desktop installer build | `app/` | `pnpm run build:desktop` | | Workspace builds | `app/` | `pnpm run build` | | Desktop TS tests | `app/apps/desktop/` | `pnpm test` | | Deskt …[+355 chars]
  • AGENTS.md: They require Postgres and migrations, run serially, and are not cached.
  • AGENTS.md: From `app/apps/desktop/`, run `pnpm run simulate:windows` or `pnpm run simulate:macos`.
  • AGENTS.md: Run checks relevant to the change.
  • AGENTS.md: CI tests run automatically on pushes to `staging`, not on PR events or again on production promotion (manual dispatch remains available).
  • AGENTS.md: Run relevant local checks before pushing;
  • CLAUDE.md: **Desktop app** (`app/apps/desktop`) — the product people install.
  • CLAUDE.md: Because of that, review happens *before* main: PRs target the long-lived **`staging`** branch, and every push to it runs `.github/workflows/staging-release.yml`, which publishes a separate auto-updating **"Baalda Staging"** app (`com.baalda.context.staging`, version `<base>-staging.<ru …[+210 chars]
  • CLAUDE.md: pnpm pinned via `packageManager`, activate with `corepack enable`);
  • CLAUDE.md: Run `pnpm install` once from `app/`.
  • CLAUDE.md: pnpm run db:up # Postgres 16 in Docker, host port 5439
  • CLAUDE.md: pnpm run migrate # apply migrations/*.sql in order
  • CLAUDE.md: pnpm run dev # tsx watch; HTTP :3010, Hocuspocus WS :3011, GET /health
  • CLAUDE.md: **Desktop** (from `app/`): `pnpm run dev:desktop` (= `pnpm --filter desktop tauri dev --config src-tauri/tauri.dev.conf.json`;
  • CLAUDE.md: Build: `pnpm run build:desktop`.
  • CLAUDE.md: Everything: `pnpm test` from `app/` (= `turbo run test`, both workspaces;
  • CLAUDE.md: Server (`app/apps/server`): `pnpm test` (vitest).
  • CLAUDE.md: Desktop TS (`app/apps/desktop`): `pnpm test` (vitest, node env).
  • CLAUDE.md: Install = validate shas → stage in `.baalda-staging-<uuid>` → write the marker last → re-verify staged hashes → rename the old dir aside, rename staging in, roll back on failure (never rename over a dir).
  • CLAUDE.md: Install/remove share one process-wide lock;
  • CLAUDE.md: **External writers are first-class** (`handleLocalFileChanged` in `docSession.ts`): a watcher event for a non-open note routes to the sync layer — unmapped/structural changes trigger the debounced registry pull (register + upload), mapped notes get a debounced `ContentUploader` run wit …[+142 chars]
  • CLAUDE.md: **No 0-byte placeholders when a bootstrap will deliver** (`registry.ts pendingFromBootstrap`, `InboundHost.bootstrapWillDeliver`): a pull large enough for the bulk path (`useBulkPath`) whose bootstrap is guaranteed to run records server-only notes instead of writing placeholders, and t …[+139 chars]
  • CLAUDE.md: When the download ends however it ends, `materializePendingFromBootstrap` writes create-only placeholders for what it did not deliver (the server-empty `ready.empty` class, or a cancelled run), re-resolved by `doc_id`.
  • CLAUDE.md: open Skills pages, the skill page and the sidebar shortcut also reload on it via `useSkillsChanged`, so a teammate's add shows live), every 2 min (the frame only covers the OPEN vault), on coming back to the app (≤ every 30 s) and on Check now, one run at a time;
  • CLAUDE.md: a failed install waits 10 min between tries and stops after 3 retries for that version (Check now or a restart starts over).
  • CLAUDE.md: The API client is shared and a server switch repoints it before App's effect stops the host, so a run halts (plans and acts on nothing) once the client's base URL differs from the host's, and `store.setServerUrl` pauses the host first (`pauseSkillsSync`, resumed unless a switch to anoth …[+15 chars]
  • CLAUDE.md: migrations run pre-deploy via `node dist/db/migrate.js`).
  • CLAUDE.md: State goes ONLY to a row this call created, or a row that already carried the SAME id in this vault (an old client or an interrupted run registered it and never pushed), after `syncPermission` and a covered check under the doc lock.
  • CLAUDE.md: the Pro gate and a dry-run `registerFile` (adopt-by-path, `path_folder_mismatch`, create permission, frozen root, rolled back) run at intent BEFORE any row exists, with the same statuses/codes as `POST /api/files`.
  • CLAUDE.md: `pnpm messages` wraps them.
  • CLAUDE.md: owners/admins see every skill but install only at their own level (`docs/SKILLS.md` addendum "Who gets a skill").
  • CLAUDE.md: While on, the offline key holder can read any vault: the website must say so. · uses the network
  • CLAUDE.md: `crypto/null-out.ts` (run from the backfill tick after `complete`) clears plaintext only when the backfill is complete, a fresh `encryptionStatus` is 0 and `VAULT_PLAINTEXT_RETENTION_DAYS` have passed: per row, open the sealed copy, compare byte for byte, clear under `WHERE plaintext = …[+32 chars]
  • CLAUDE.md: `doc_updates`/`doc_snapshots` clears run under the doc's EXCLUSIVE advisory lock (`withDocWriteLock`, the one compaction holds), so a converting compaction can never fold a just-cleared row's plaintext back into its dual row.
  • Medium risk: runs-instruction-instruction-network (.claude/skills/baalda-guide/SKILL.md:19)
  • Medium risk: runs-instruction-instruction-network (CLAUDE.md:1099)
  • Low risk: network-instructions (.agents/skills/relaunch/SKILL.md:60)
  • Low risk: network-instructions (.claude/skills/relaunch/SKILL.md:68)

Attribution and licence

First committed by
GitHub avatar of naveedharrinaveedharri
Publisher
Naveed Harri (Community)
Source
naveedharri/baalda · commit 90929b5
Licence
Apache License 2.0 (A licence file holds personal contact details, so AutoGineer links to the files instead of copying them.)
Synced
Contributors
naveedharri, nawazxz, rtowner-es

AutoGineer is not affiliated with or endorsed by naveedharri.

Install from source

A licence file holds personal contact details, so AutoGineer links to the files instead of copying them. naveedharri/baalda at 90929b5